@ictechgy/context-guard 0.4.13 → 0.4.15

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

@@ -79,6 +79,7 @@ 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 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
 context-guard-cache-score --input prompt.json --provider openai --json
 context-guard-tool-prune select --catalog tools.json --query "review failing tests" --top 5 --budget-bytes 12000 --json
@@ -90,6 +91,10 @@ context-guard-statusline-merged
 
 ## 헬퍼가 하는 일
 
+모든 pack build는 기존 `pack_id`를 바꾸지 않고 렌더링된 byte의 SHA-256 `content_address`를 포함합니다. `build`와 `auto`의 선택적 `--delta-from-pack-id PACK_ID`는 private local receipt 하나만 bounded/fail-soft 방식으로 비교합니다. `rolling_delta`는 진단 전용이고 selection이나 pack 본문을 바꾸지 않으며 provider token/cost savings claim이 아닙니다. 진단은 `--json` 출력 또는 저장된 artifact receipt에서만 보고됩니다. `--no-artifact`를 쓰면 진단 보고에 `--json`이 필요하며, 기존 text stdout은 정확한 pack 본문을 그대로 유지합니다.
+
+선택적 `build`/`auto --sketch-duplicate-veto`는 sanitized slice에 rank-stable pre-budget gate를 적용하며 `suggest`는 그대로 둡니다. exact digest 후보는 byte로 확인합니다. 근사 gate는 고정 framing의 Unicode-casefold 순서 보존 5-token shingle, bottom 64 unique digest, 양쪽 최소 12, inclusive 0.90의 sketch-set Jaccard입니다. 짧은 sketch는 exact-only입니다. eligible pair 100,000개 검증 뒤 실제 skipped pair에서 fail open하고 이후 digest-only로 동작합니다. winner가 최종 budget에서 렌더링되지 않을 수 있으므로 누락 source 자체의 exact retrieval을 편집/근거 사용 전에 확인하십시오. `sketch_duplicate_source`, standalone build/`auto.build`의 `sketch_duplicate_veto.comparison_cap_reached`, flagged text의 `sketch_comparison_cap_reached=true|false`만 receipt 실패와 무관하게 관측됩니다. fingerprint, match identity, overlap, score, provider token/cost savings claim은 내보내지 않으며 flag-off 동작은 호환됩니다.
+
 - **설정 마법사**는 `.claude/settings.json`을 덮어쓰지 않고 병합한 뒤, 읽기 전용 `context-guard-diet scan` 요약을 보여줍니다. 자동화에서 적용 후 검사 요약이 필요 없으면 `--no-diet-scan`을 사용하세요. `PATH` helper fallback은 기본적으로 꺼져 있으며, `--allow-path-helper-fallback`과 identity 검증을 통과해야만 사용됩니다.
 - **컨텍스트 관리 스캐너**는 누락된 `permissions.deny` 가드레일, Bash 출력 축약 훅, 상태표시줄 설정, 넓은 읽기 허용, 비용이 큰 기본 모델/추론 강도, 많은 MCP 서버, 크거나 민감해 보이는 에이전트 규칙 파일, 부피가 크거나 민감해 보이는 로컬 경로에 대한 자문형 context-exclusion 추천을 확인합니다.
 - **대용량 읽기 가드와 심볼 리더**는 파일 전체 읽기 전에 검색, 심볼 구간, 작은 줄 범위 읽기 순서로 에이전트를 안내합니다. Python, JavaScript/TypeScript, Go, Rust 소스 구간 읽기를 지원합니다.
@@ -119,10 +124,24 @@ brief 모드는 코딩 에이전트가 군더더기를 줄이도록 요청하되
 
 ContextGuard는 모델 토큰을 줄이기 위해 작업을 외부 AI 서비스로 전송하지 않습니다. 모든 헬퍼 명령은 로컬에서 동작합니다. 로컬 RAM/디스크 보관본은 다음에 보낼 컨텍스트를 줄이는 데 도움될 수 있지만 provider prompt cache를 대체하지 않습니다. Anthropic 배포나 청구 설명 전에는 공식 prompt caching/pricing 문서를 다시 확인하세요: https://docs.anthropic.com/en/build-with-claude/prompt-caching 및 https://platform.claude.com/docs/en/about-claude/pricing.
 
-미래 learned, self-hosted 최적화 아이디어는 [`research/experimental-token-reduction-radar.md`](https://github.com/ictechgy/context-guard/blob/main/research/experimental-token-reduction-radar.md)에 gated experiment로 기록하며, fixture-only 시작 예시는 [`docs/experimental-benchmark-fixtures.md`](https://github.com/ictechgy/context-guard/blob/main/docs/experimental-benchmark-fixtures.md)에 둡니다. learned compression은 `context-guard experiments plan learned-compression` dry-run checker와 명시적 `context-guard experiments emit learned-compression` caller-supplied candidate emitter만 shipped 상태이고, self-hosted-metrics-ledger는 dry-run preview와 명시적 `context-guard experiments record self-hosted-metrics-ledger` local JSONL record를 제공하며, dry-run preview는 ledger 파일을 쓰지 않습니다. visual crop/OCR은 caller-supplied evidence-pack emit, context-diff는 verified-receipt caller-supplied replacement emit만 제공합니다. local proxy는 `context-guard experiments plan local-proxy` localhost-only dry-run advisory plan, design-only `context-guard experiments plan local-proxy-external-forwarding` gate, 명시적 `context-guard experiments record local-proxy-runtime-gate --ledger-jsonl ...` gate row record, private ready-file nonce가 필요한 one-shot `context-guard experiments serve local-proxy` loopback forwarding MVP와 successful forwarded request용 optional shifted-cost diagnostic JSONL row만 shipped 상태입니다. record는 no listener/no traffic forwarding/no DNS lookup/no external service/no API-key persistence boundary를 유지하고, serve는 private ready-file nonce, literal loopback IP, `--once`, credential-free request만 허용하고 CONNECT/TLS proxying도 지원하지 않습니다. `--response-sandbox`는 safe UTF-8 response text만 local artifact receipt로 저장하고 raw body 대신 redacted rehydration command template가 담긴 compact envelope를 돌려주며 hosted token/cost savings claim은 아닙니다. `--diagnostic-ledger-jsonl`은 successful forwarded request 뒤에만 진단 row를 쓰며 raw header/body나 hosted-savings evidence를 저장하지 않습니다. `plan local-proxy-external-forwarding`은 threat model, HTTPS allowlist, credential redaction, provider-evidence boundary를 점검하는 dry-run design gate이고 listener, DNS lookup, external service call, traffic forwarding, credential persistence, external proxy forwarding runtime, hosted savings claim을 제공하지 않습니다. learned/synthetic compressor 실행·embedding·reranker·model call·생성형 replacement, generated OCR/crop 또는 visual-token pruning, self-hosted KV/latent runtime 최적화, one-shot literal-loopback local proxy MVP를 넘어선 external/daemon/credential-bearing proxy forwarding runtime은 shipped가 아닙니다. 이 radar와 fixture는 provider가 측정한 matched-task 근거 없이 hosted API 절감을 주장하지 않습니다. Radar의 later-roadmap gate는 neural/semantic compression, trust-tiered injection-aware compression, generated visual-token reduction, broader local proxy forwarding constraint도 별도 미래 PR이 gate를 통과하기 전까지 experimental/non-shipped로 묶습니다.
+미래 learned, self-hosted 최적화 아이디어는 [`research/experimental-token-reduction-radar.md`](https://github.com/ictechgy/context-guard/blob/main/research/experimental-token-reduction-radar.md)에 gated experiment로 기록하며, fixture-only 시작 예시는 [`docs/experimental-benchmark-fixtures.md`](https://github.com/ictechgy/context-guard/blob/main/docs/experimental-benchmark-fixtures.md)에 둡니다. learned compression은 `context-guard experiments plan learned-compression` dry-run checker와 명시적 `context-guard experiments emit learned-compression` caller-supplied candidate emitter만 shipped 상태이고, self-hosted-metrics-ledger는 dry-run preview와 명시적 `context-guard experiments record self-hosted-metrics-ledger` local JSONL record를 제공하며, dry-run preview는 ledger 파일을 쓰지 않습니다. visual crop/OCR은 caller-supplied evidence-pack emit, image-context-pack은 pxpipe-inspired image/context packing 평가를 위한 plan-only dry-run gate, semantic-checkpoint는 review용 task-state checkpoint 계획을 위한 plan-only/eval-only gate, context-diff는 verified-receipt caller-supplied replacement emit만 제공합니다. image-context-pack은 exact text artifact fallback, protected-zone denial, provider-boundary acknowledgement for provider-measured matched tasks, missed-context guardrail, 그리고 visual-crop-ocr이 기존 caller-supplied visual evidence-pack surface라는 plan output 확인이 필요하며, image rendering, OCR 실행, image parsing, model/provider call, proxy traffic, binary artifact 저장, replacement evidence 출력, hosted token/cost savings claim을 하지 않습니다. semantic-checkpoint는 CLI flag가 optional이지만 JSON readiness에서 exact context fallback/re-expand, provider-boundary ack, protected-zone policy `deny`, missed-context note, provenance review note가 없으면 blocked이며, `--missing-provenance-note`는 `none known after review` 같은 검토 확인 문구일 수 있습니다. 허용되는 re-expand command는 `context-guard-artifact get <id> --full` 또는 `context-guard artifact get <id> --full` 형태이고, emit/record/serve runtime, 새 `context-guard-semantic-checkpoint` binary, file write, transcript/prompt edit, model/provider/network call, replacement context, hosted token/cost savings claim은 없습니다. local proxy는 `context-guard experiments plan local-proxy` localhost-only dry-run advisory plan, design-only `context-guard experiments plan local-proxy-external-forwarding` gate, 명시적 `context-guard experiments record local-proxy-runtime-gate --ledger-jsonl ...` gate row record, private ready-file nonce가 필요한 one-shot `context-guard experiments serve local-proxy` loopback forwarding MVP와 successful forwarded request용 optional shifted-cost diagnostic JSONL row만 shipped 상태입니다. record는 no listener/no traffic forwarding/no DNS lookup/no external service/no API-key persistence boundary를 유지하고, serve는 private ready-file nonce, literal loopback IP, `--once`, credential-free request만 허용하고 CONNECT/TLS proxying도 지원하지 않습니다. `--response-sandbox`는 safe UTF-8 response text만 local artifact receipt로 저장하고 raw body 대신 redacted rehydration command template가 담긴 compact envelope를 돌려주며 hosted token/cost savings claim은 아닙니다. `--diagnostic-ledger-jsonl`은 successful forwarded request 뒤에만 진단 row를 쓰며 raw header/body나 hosted-savings evidence를 저장하지 않습니다. `plan local-proxy-external-forwarding`은 threat model, HTTPS allowlist, credential redaction, provider-evidence boundary를 점검하는 dry-run design gate이고 listener, DNS lookup, external service call, traffic forwarding, credential persistence, external proxy forwarding runtime, hosted savings claim을 제공하지 않습니다. learned/synthetic compressor 실행·embedding·reranker·model call·생성형 replacement, generated OCR/crop, visual-token pruning, plan-only image-context-pack dry-run gate를 넘어선 image-context-pack rendering/runtime, plan-only semantic-checkpoint gate를 넘어선 emit/record/serve runtime이나 replacement context/file-writing checkpoint store/transcript-prompt edit/provider-backed checkpointing, self-hosted KV/latent runtime 최적화, one-shot literal-loopback local proxy MVP를 넘어선 external/daemon/credential-bearing proxy forwarding runtime은 shipped가 아닙니다. 이 radar와 fixture는 provider가 측정한 matched-task 근거 없이 hosted API 절감을 주장하지 않습니다. Radar의 later-roadmap gate는 neural/semantic compression, trust-tiered injection-aware compression, generated visual-token reduction, broader local proxy forwarding constraint도 별도 미래 PR이 gate를 통과하기 전까지 experimental/non-shipped로 묶습니다.
+
+`plan proof-carrying-context`는 bounded repeatable inline JSON의 proof-envelope metadata 구문과 정의된 일관성만 확인하는 기본 비활성 plan-only readiness gate입니다. Caller timestamp를 보존하지만 현재 시간이나 freshness는 검사하지 않고 protected-zone policy는 선언 전용입니다. 이 plan command에는 range bounds, receipt storage, source content, SHA-256, timestamp freshness, rehydration이 unchecked warning으로 남으며 source/artifact/config/stdin read, file write, model/provider/network/subprocess call, context 생성·대체, `emit`/`record`/`serve` runtime, 새 binary, hosted savings claim은 없습니다. `candidate_replacement`는 항상 `null`입니다.
+
+`verify proof-carrying-context`는 별도의 read-only local verifier입니다. 문서 fixture는 정확한 UTF-8 문자열 `ContextGuard proof fixture\n`(27 bytes, 1 line)이고 SHA-256은 `12637068ee51f2ddfe27f1c00836a51cb54ba6a5cfca7f2301a4a45fbade2d14`입니다. Explicit artifact directory 하나만 사용하고 fallback search를 수행하지 않고 symlink를 follow하지 않으며 effective-user-owned directory `0700`과 두 receipt leaf 모두 mode `0600`을 요구합니다. Bounded whole-file read로 receipt/proof SHA, byte/line count, range bounds만 확인하고 range content는 retrieve/echo하지 않습니다. Exit `0`은 local binding pass, exit `2`는 verification failure이며 timestamp freshness/protected-zone semantics는 unchecked입니다. Rehydrate command는 syntax/receipt binding만 확인하고 실행하지 않으며 `candidate_replacement: null`을 유지하고 replacement/omission/hosted-savings authority를 부여하지 않습니다.
+
+```bash
+context-guard experiments plan semantic-checkpoint --json --goal "preserve current task state for review" --constraint "do not rewrite protected evidence" --decision "ship plan-only semantic-checkpoint gate first" --open-task "verify exact fallback before any checkpoint is used" --evidence-handle "roadmap=contextguard-artifact:0123456789abcdef" --missing-provenance-note "none known after review" --unresolved-question "which provenance handle fields become mandatory later" --exact-context-fallback-receipt 0123456789abcdef --reexpand-command "context-guard-artifact get 0123456789abcdef --full" --provider-boundary-ack --protected-zone-policy deny --missed-context-note "raw transcript remains retrievable before checkpoint metadata is used"
+context-guard experiments plan proof-carrying-context --json --proof-unit-json '{"source_label":"context-filesystem-roadmap","receipt_id":"0123456789abcdef","content_sha256":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","safe_range":{"kind":"lines","start":82,"end":85},"captured_at":"2026-07-10T04:11:12Z","transform_policy":"safe_range_extract","rehydrate_command":"context-guard-artifact get 0123456789abcdef --full"}' --provider-boundary-ack --protected-zone-policy deny
+context-guard experiments verify proof-carrying-context --artifact-dir ./artifacts --proof-unit-json '{"source_label":"context-filesystem-roadmap","receipt_id":"0123456789abcdef","content_sha256":"12637068ee51f2ddfe27f1c00836a51cb54ba6a5cfca7f2301a4a45fbade2d14","safe_range":{"kind":"lines","start":1,"end":1},"captured_at":"2026-07-10T04:11:12Z","transform_policy":"safe_range_extract","rehydrate_command":"context-guard-artifact get 0123456789abcdef --full"}' --json
+```
 
 교차 에이전트 규칙 스니펫은 안내용입니다. 대상 에이전트가 반드시 따른다고 보장할 수 없으므로, 절감 주장이 필요하면 실제 전후 동작을 직접 측정하세요.
 
+## 로컬 MCP 어댑터
+
+`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 절감도 주장하지 않습니다.
+
 ## 로컬 배포 테스트
 
 마켓플레이스 저장소 루트에서 실행합니다.
@@ -144,6 +163,16 @@ claude --plugin-dir ./plugins/context-guard
 /plugin install context-guard@context-guard
 ```
 
+### 실험적 semantic-GC plan gate
+
+`semantic-gc`는 기본 비활성화된 deny 전용 계획 검토 gate입니다. 기본 비활성화는 registry intent를 뜻하며, 명시적 plan CLI는 계속 실행할 수 있지만 omission이나 runtime action을 활성화하지 않습니다. 전체 envelope나 graph topology가 모호하면 graph evaluation을 억제합니다. 도달할 수 없는 node는 semantic irrelevance의 증명이 아니라 검토 후보일 뿐이며 omission과 runtime action은 승인되지 않습니다. missed-context note는 신뢰되지 않은 입력입니다. 이 planner는 context/artifact 내용을 읽지 않고 provenance, fallback, provider, hosted 절감을 검증하지 않습니다. Exit 0은 `ready_for_plan_review`만 뜻하며 delete/omit 권한이 아닙니다.
+
+context-guard experiments plan semantic-gc --json --context-unit-json '{"schema":"contextguard.semantic-gc-unit.v1","unit_id":"root","references":[],"is_root":true,"protected_zone":false}' --context-unit-json '{"schema":"contextguard.semantic-gc-unit.v1","unit_id":"orphan","references":[],"is_root":false,"protected_zone":false,"content_sha256":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","provenance":{"source_label":"canonical-example","receipt_id":"0123456789abcdef"},"missed_context_note":"A reviewer could lose the orphaned rationale.","exact_fallback_command":"context-guard-artifact get 0123456789abcdef --full"}' --provider-boundary-ack --human-review-ack --protected-zone-policy deny
+
+`static-relevance`는 호출자가 제공한 제한된 static evidence를 컴파일하는 기본 비활성화 기능입니다. 누락된 signal은 모든 slice와 review ordering을 억제하며, 빈 edge list도 검증된 관측이 아니라 선언입니다. protected path match와 명시적 보호 reason은 사람 검토에서 먼저 보게 하는 hard retention veto일 뿐입니다. 이 명령은 계획 검토 전용이며 repo를 읽지 않고, git을 호출하지 않으며, parser·provider·network·subprocess도 호출하지 않습니다. 결정적 review order에는 omit 권한이 없고 삭제·deprioritization·대체·runtime action도 승인하지 않습니다.
+
+context-guard experiments plan static-relevance --json --relevance-unit-json '{"schema":"contextguard.static-relevance-unit.v1","unit_id":"src/cli.py::main","path":"src/cli.py","task_anchor":true,"protection_reasons":[],"symbol":{"name":"main","kind":"function","start_line":1,"end_line":40},"symbol_references":[],"dataflow_predecessors":[],"dataflow_successors":[],"git":{"blame_age_days":2,"blame_contributor_count":1,"path_change_count_90d":3}}' --protected-path-policy deny --provider-boundary-ack
+
 ## 라이선스
 
 Copyright 2026 jinhongan. Apache License 2.0으로 배포됩니다. [LICENSE](LICENSE)와 [NOTICE](NOTICE)를 참고하세요.

package/plugins/context-guard/README.md

@@ -85,6 +85,7 @@ 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 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
 context-guard-cache-score --input prompt.json --provider openai --json
 context-guard cache-score --input prompt.txt --provider anthropic --json
@@ -97,6 +98,10 @@ context-guard-statusline-merged
 
 ## What the helpers do
 
+Every pack build includes a rendered-byte SHA-256 `content_address` without changing the legacy `pack_id`. `build` and `auto` accept opt-in `--delta-from-pack-id PACK_ID` for bounded, fail-soft diagnostics against exactly one private local receipt; `rolling_delta` is diagnostic-only, changes no selection or pack content, and is not a provider token/cost savings claim. Diagnostics are reported only in `--json` output or a stored artifact receipt; with `--no-artifact`, `--json` is required to report them, while legacy text stdout remains the exact pack body.
+
+Opt-in `build`/`auto --sketch-duplicate-veto` applies a rank-stable pre-budget gate to sanitized slices; `suggest` stays unchanged. Exact digest candidates are byte-confirmed. The approximate gate is sketch-set Jaccard over frozen Unicode-casefolded ordered five-token shingles: bottom 64 unique digests, minimum 12 on both sides, inclusive 0.90. Short sketches are exact-only. After 100,000 verified eligible pairs, the first skipped pair fails open and later work is digest-only. A winner may not render under the final budget, so use the omitted source's own exact retrieval before editing or relying on it. Only `sketch_duplicate_source`, standalone build/`auto.build` `sketch_duplicate_veto.comparison_cap_reached`, and flagged text `sketch_comparison_cap_reached=true|false` are observable, even when receipt storage fails. No fingerprint, match identity, overlap, score, provider token/cost savings claim is emitted; flag-off behavior is compatible.
+
 - **Setup wizard** merges `.claude/settings.json` instead of replacing it, then prints a read-only `context-guard-diet scan` summary. Use `context-guard doctor` or `context-guard setup --verify` for a read-only health check before applying setup; use `--no-diet-scan` when automation needs setup output without the post-apply scan. `PATH` helper fallback is default-off and requires `--allow-path-helper-fallback` plus identity validation.
 - **Context management scanner** checks missing `permissions.deny` guardrails, Bash trim hook/statusline setup, broad read allows, high default model/effort, many MCP servers, large or secret-like agent rule files, and advisory context-exclusion recommendations for bulky/sensitive local paths. Its `--top` cap applies to both context-like files and context-exclusion recommendations.
 - **Structural-waste doctor** is an opt-in read-only `context-guard-diet structural-waste` report for duplicate rule units, stale Python import candidates, unused skill candidates, excessive MCP/tool schema catalogs, and repeated file reads or duplicate tool calls in local JSON/JSONL logs. It does not mutate config, call the network, or print raw prompt/tool-input text; low-confidence import/skill findings are review prompts, not delete instructions.
@@ -128,7 +133,7 @@ These helpers reduce common sources of context bloat, but they do not guarantee
 
 ContextGuard also does not send work to external AI providers to save model tokens. All helper commands run locally. Local RAM/disk receipts can reduce what you choose to send, but they do not replace a provider prompt cache. Before release or billing claims for Anthropic, recheck the official prompt-caching and pricing docs: https://docs.anthropic.com/en/build-with-claude/prompt-caching and https://platform.claude.com/docs/en/about-claude/pricing.
 
-Future learned, multimodal, and self-hosted optimization ideas are tracked in [`research/experimental-token-reduction-radar.md`](https://github.com/ictechgy/context-guard/blob/main/research/experimental-token-reduction-radar.md), with fixture-only starters in [`docs/experimental-benchmark-fixtures.md`](https://github.com/ictechgy/context-guard/blob/main/docs/experimental-benchmark-fixtures.md). ContextGuard ships dry-run planners/checkers for local-proxy advisory plans and design-only external-forwarding gates, plus narrow explicit local runtimes for caller-supplied context-diff replacement payloads, caller-supplied visual crop/OCR evidence packs, caller-supplied learned-compression prose candidates, self-hosted metrics JSONL sidecar records, local-proxy runtime-gate JSONL records, one-shot `serve local-proxy` loopback forwarding with a private ready-file nonce, optional `--response-sandbox` compact artifact envelopes for safe UTF-8 responses, and optional shifted-cost diagnostic JSONL rows for successful forwarded requests. Learned/synthetic compressor execution beyond the caller-supplied candidate emitter, embeddings, rerankers, model calls, generated replacement text, screenshot capture, image cropping, OCR execution, image parsing, external OCR/image services, output-file evidence writes, self-hosted KV/latent runtime optimization beyond explicit local metrics recording, and external/daemon/hostname-DNS, credential-bearing, or external proxy forwarding beyond literal-loopback one-request HTTP forwarding are not shipped. That radar and the fixtures do not claim hosted API savings without provider-measured matched-task evidence. The radar's later-roadmap gates also keep neural/semantic compression, trust-tiered injection-aware compression, generated visual-token reduction, and broader local proxy forwarding constraints experimental/non-shipped until a separate future PR satisfies those gates.
+Future learned, multimodal, and self-hosted optimization ideas are tracked in [`research/experimental-token-reduction-radar.md`](https://github.com/ictechgy/context-guard/blob/main/research/experimental-token-reduction-radar.md), with fixture-only starters in [`docs/experimental-benchmark-fixtures.md`](https://github.com/ictechgy/context-guard/blob/main/docs/experimental-benchmark-fixtures.md). ContextGuard ships dry-run planners/checkers for a plan-only `image-context-pack` evaluation gate, local-proxy advisory plans, and design-only external-forwarding gates, plus narrow explicit local runtimes for caller-supplied context-diff replacement payloads, caller-supplied visual crop/OCR evidence packs, caller-supplied learned-compression prose candidates, self-hosted metrics JSONL sidecar records, local-proxy runtime-gate JSONL records, one-shot `serve local-proxy` loopback forwarding with a private ready-file nonce, optional `--response-sandbox` compact artifact envelopes for safe UTF-8 responses, and optional shifted-cost diagnostic JSONL rows for successful forwarded requests. Learned/synthetic compressor execution beyond the caller-supplied candidate emitter, embeddings, rerankers, model calls, generated replacement text, screenshot capture, image cropping, OCR execution, image parsing, external OCR/image services, output-file evidence writes, generated image-context-pack renderers, binary/image artifact fallback, pxpipe-style proxy/runtime, self-hosted KV/latent runtime optimization beyond explicit local metrics recording, and external/daemon/hostname-DNS, credential-bearing, or external proxy forwarding beyond literal-loopback one-request HTTP forwarding are not shipped. That radar and the fixtures do not claim hosted API savings without provider-measured matched-task evidence. The radar's later-roadmap gates also keep neural/semantic compression, trust-tiered injection-aware compression, generated visual-token reduction, and broader local proxy forwarding constraints experimental/non-shipped until a separate future PR satisfies those gates.
 
 ## Experimental opt-ins
 
@@ -141,6 +146,10 @@ context-guard experiments plan context-diff-compaction --json < change.diff
 context-guard experiments emit context-diff-compaction --receipt-id <artifact-id> --reexpand-command "context-guard-artifact get <artifact-id> --full" --replacement-file compact-diff.txt --json < change.diff
 context-guard experiments plan visual-crop-ocr --json --full-evidence-receipt <id> --crop-label <label> --crop-bounds 0,0,100,100 --image-size 800,600 --missed-context-note "outside crop omitted"
 context-guard experiments emit visual-crop-ocr --json --full-evidence-receipt <id> --crop-label <label> --crop-bounds 0,0,100,100 --image-size 800,600 --ocr-text "visible text" --ocr-confidence 0.9 --ocr-error-note "glyph may be uncertain" --missed-context-note "outside crop omitted"
+context-guard experiments plan image-context-pack --json --exact-text-fallback-receipt <id> --reexpand-command "context-guard-artifact get <id> --full" --provider-boundary-ack --protected-zone-policy deny --missed-context-note "omitted text remains retrievable before any future image pack is used" --image-size 800,600 --packed-image-size 400,300
+context-guard experiments plan semantic-checkpoint --json --goal "preserve current task state for review" --constraint "do not rewrite protected evidence" --decision "ship plan-only semantic-checkpoint gate first" --open-task "verify exact fallback before any checkpoint is used" --evidence-handle "roadmap=contextguard-artifact:0123456789abcdef" --missing-provenance-note "none known after review" --unresolved-question "which provenance handle fields become mandatory later" --exact-context-fallback-receipt 0123456789abcdef --reexpand-command "context-guard-artifact get 0123456789abcdef --full" --provider-boundary-ack --protected-zone-policy deny --missed-context-note "raw transcript remains retrievable before checkpoint metadata is used"
+context-guard experiments plan proof-carrying-context --json --proof-unit-json '{"source_label":"context-filesystem-roadmap","receipt_id":"0123456789abcdef","content_sha256":"aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa","safe_range":{"kind":"lines","start":82,"end":85},"captured_at":"2026-07-10T04:11:12Z","transform_policy":"safe_range_extract","rehydrate_command":"context-guard-artifact get 0123456789abcdef --full"}' --provider-boundary-ack --protected-zone-policy deny
+context-guard experiments verify proof-carrying-context --artifact-dir ./artifacts --proof-unit-json '{"source_label":"context-filesystem-roadmap","receipt_id":"0123456789abcdef","content_sha256":"12637068ee51f2ddfe27f1c00836a51cb54ba6a5cfca7f2301a4a45fbade2d14","safe_range":{"kind":"lines","start":1,"end":1},"captured_at":"2026-07-10T04:11:12Z","transform_policy":"safe_range_extract","rehydrate_command":"context-guard-artifact get 0123456789abcdef --full"}' --json
 context-guard experiments plan learned-compression --json --sanitized --trusted-source --exact-fallback-receipt <id> --reexpand-command "context-guard-artifact get <id> --full" < sanitized-prose.txt
 context-guard experiments emit learned-compression --json --sanitized --trusted-source --exact-fallback-receipt <id> --reexpand-command "context-guard-artifact get <id> --full" --replacement-file compact-prose.txt < sanitized-prose.txt
 context-guard experiments plan self-hosted-metrics-ledger --json --latency-ms 123.5 --peak-memory-mb 2048 --quality-score 0.98
@@ -153,10 +162,22 @@ context-guard experiments enable output-receipt-trim --root .
 context-guard experiments disable output-receipt-trim --root .
 ```
 
-Use `--config <path>` only for an explicit project-local override. Registry entries include risk, gate requirements, explicit command/flag surfaces, and claim boundaries; hosted API token/cost savings still require provider-measured matched-task evidence. The registry can discover existing explicit-flag experiments such as `context-guard-trim-output --digest ... --artifact-receipt` and `context-guard-compress --protected-policy`, run dry-run advisory planners such as `context-guard experiments plan context-diff-compaction`, `context-guard experiments plan visual-crop-ocr`, `context-guard experiments plan learned-compression`, `context-guard experiments plan self-hosted-metrics-ledger`, `context-guard experiments plan local-proxy`, and design-only `context-guard experiments plan local-proxy-external-forwarding`, and run explicit local runtimes such as `context-guard experiments emit context-diff-compaction ...`, `context-guard experiments emit visual-crop-ocr ...`, `context-guard experiments emit learned-compression ...`, `context-guard experiments record self-hosted-metrics-ledger ...`, `context-guard experiments record local-proxy-runtime-gate ...`, `context-guard experiments serve local-proxy ...`, and successful-forward `context-guard experiments serve local-proxy --diagnostic-ledger-jsonl ...` diagnostics. The context-diff emit runtime only emits caller-supplied compact replacements when reviewable hunks, exact local artifact re-expand metadata whose stored content matches the input diff, and a smaller replacement are present; it does not generate semantic compression or permit hosted savings claims. The visual lane ships a dry-run planner plus an explicit local evidence-pack emitter: both use only caller-supplied full-evidence receipts, crop metadata, OCR text, confidence/error notes, and missed-context notes; screenshot capture, image cropping, OCR execution, image parsing, external OCR/image services, output-file writes, and hosted savings claims are not shipped. The learned-compression lane ships a deny-by-default dry-run policy check plus an explicit local candidate emitter for caller-supplied compact prose with verified exact fallback content: learned/synthetic compressor execution, embeddings, rerankers, model calls, subprocesses, external services, generated replacement text, and hosted savings claims are not shipped. The self-hosted metrics planner emits a dry-run ledger-compatible preview for explicit local/model-server latency, memory, quality, energy, throughput, and local-cost metrics; the dry-run preview does not write a ledger, while `context-guard experiments record self-hosted-metrics-ledger --ledger-jsonl ...` writes only local JSONL sidecars and still does not permit hosted API token/cost savings claims. The local-proxy planner emits localhost-only advisory metadata only, while `context-guard experiments record local-proxy-runtime-gate --ledger-jsonl ...` appends one local gate row only after localhost-only metadata and `--runtime-gate-ack`: it starts no listener, forwards no traffic, and performs no DNS lookup. `context-guard experiments serve local-proxy ...` is the separate forwarding MVP: it requires `--forwarding-gate-ack --once`, a private `--ready-file` nonce handoff, literal loopback bind/target IPs, no hostname DNS targets, nonzero ports, byte/time limits, and credential-free requests; it performs no external forwarding, no CONNECT/TLS proxying, no API-key persistence, and no hosted-savings claim. `--response-sandbox` can store safe UTF-8 response text as a sanitized local artifact receipt and return a compact envelope with redacted rehydration command templates; it does not claim hosted token/cost savings. `--diagnostic-ledger-jsonl` writes one shifted-cost diagnostic row only after a successful forwarded request, with no raw headers/bodies and no hosted-savings evidence. `plan local-proxy-external-forwarding` emits threat-model/allowlist/redaction/provider-evidence design metadata only and still starts no listener, performs no DNS lookup, calls no external service, forwards no traffic, persists no credentials, and does not ship an external proxy forwarding runtime. `experiments enable` records intent only; it does not run those helpers, remove the need for their explicit flags, or permit replacing content without exact receipt/re-expand evidence.
+`image-context-pack` is a plan-only/dry-run gate for pxpipe-inspired image/context packing evaluation. It requires exact text artifact fallback, protected-zone denial, provider-boundary acknowledgement for provider-measured matched tasks, missed-context guardrails, and acknowledgement in the plan output that `visual-crop-ocr` is the existing caller-supplied visual evidence-pack surface. It does not render images, run OCR, call models/providers, proxy traffic, store binary artifacts, emit replacement evidence, or support hosted token/cost savings.
+
+`semantic-checkpoint` is a plan-only/eval-only gate for reviewable task-state checkpoint planning. Its flags are optional at the CLI so incomplete dry runs can return JSON, but readiness remains blocked in the JSON payload until the plan includes a goal, exact fallback receipt, local re-expand command, provider-boundary acknowledgement, protected-zone policy `deny`, missed-context note, and provenance review note. `--missing-provenance-note` can be a review acknowledgement such as `none known after review`; allowed local re-expand shapes are `context-guard-artifact get <id> --full` and `context-guard artifact get <id> --full`. It has no `emit`, `record`, or `serve` runtime, no new `context-guard-semantic-checkpoint` binary, writes no files, edits no transcript or prompt, calls no model/provider/network, emits no replacement context, and makes no hosted token/cost savings claim.
+
+`plan proof-carrying-context` is the default-off plan-only proof-envelope metadata readiness gate. It accepts bounded repeatable inline JSON and validates syntax/defined consistency only; caller timestamps are preserved without current-time generation or freshness checks. Protected-zone policy is declared-only, while range bounds, receipt storage, source content, SHA-256, timestamp freshness, and rehydration stay unchecked and visible as warnings. This plan command reads no source/artifact/config/stdin content, writes no files, invokes no model/provider/network/subprocess, generates or replaces no context (`candidate_replacement` is always `null`), exposes no `emit`/`record`/`serve` runtime or new binary, and makes no hosted token/cost savings claim without provider-measured matched successful tasks.
+
+`verify proof-carrying-context` is the separate read-only local verifier. Its documented fixture is the exact UTF-8 string `ContextGuard proof fixture\n` (27 bytes, one line), SHA-256 `12637068ee51f2ddfe27f1c00836a51cb54ba6a5cfca7f2301a4a45fbade2d14`. It uses one explicit artifact directory, performs no fallback search, follows no symlink, and requires effective-user ownership plus directory mode `0700` and both receipt leaves with mode `0600`. It reads the complete bounded file for receipt/proof SHA, byte/line, and range-bounds verification but never retrieves or echoes range content. Exit `0` means only local bindings passed and exit `2` means verification failed; timestamp freshness and protected-zone semantics stay unchecked, rehydrate commands are syntax/receipt checked but never executed, `candidate_replacement` stays `null`, and no replacement, omission, or hosted-savings authority is granted.
+
+Use `--config <path>` only for an explicit project-local override. Registry entries include risk, gate requirements, explicit command/flag surfaces, and claim boundaries; hosted API token/cost savings still require provider-measured matched-task evidence. The registry can discover existing explicit-flag experiments such as `context-guard-trim-output --digest ... --artifact-receipt` and `context-guard-compress --protected-policy`, run dry-run advisory planners such as `context-guard experiments plan context-diff-compaction`, `context-guard experiments plan visual-crop-ocr`, `context-guard experiments plan learned-compression`, `context-guard experiments plan semantic-checkpoint`, `context-guard experiments plan self-hosted-metrics-ledger`, `context-guard experiments plan local-proxy`, and design-only `context-guard experiments plan local-proxy-external-forwarding`, and run explicit local runtimes such as `context-guard experiments emit context-diff-compaction ...`, `context-guard experiments emit visual-crop-ocr ...`, `context-guard experiments emit learned-compression ...`, `context-guard experiments record self-hosted-metrics-ledger ...`, `context-guard experiments record local-proxy-runtime-gate ...`, `context-guard experiments serve local-proxy ...`, and successful-forward `context-guard experiments serve local-proxy --diagnostic-ledger-jsonl ...` diagnostics. The context-diff emit runtime only emits caller-supplied compact replacements when reviewable hunks, exact local artifact re-expand metadata whose stored content matches the input diff, and a smaller replacement are present; it does not generate semantic compression or permit hosted savings claims. The visual lane ships a dry-run planner plus an explicit local evidence-pack emitter: both use only caller-supplied full-evidence receipts, crop metadata, OCR text, confidence/error notes, and missed-context notes; screenshot capture, image cropping, OCR execution, image parsing, external OCR/image services, output-file writes, and hosted savings claims are not shipped. The learned-compression lane ships a deny-by-default dry-run policy check plus an explicit local candidate emitter for caller-supplied compact prose with verified exact fallback content: learned/synthetic compressor execution, embeddings, rerankers, model calls, subprocesses, external services, generated replacement text, and hosted savings claims are not shipped. The semantic-checkpoint lane ships only the plan/eval gate above: no runtime emit/record/serve surface, file-writing checkpoint store, transcript/prompt edit, provider/model/network-backed checkpointing, replacement context, new binary, or hosted savings claim is shipped. The self-hosted metrics planner emits a dry-run ledger-compatible preview for explicit local/model-server latency, memory, quality, energy, throughput, and local-cost metrics; the dry-run preview does not write a ledger, while `context-guard experiments record self-hosted-metrics-ledger --ledger-jsonl ...` writes only local JSONL sidecars and still does not permit hosted API token/cost savings claims. The local-proxy planner emits localhost-only advisory metadata only, while `context-guard experiments record local-proxy-runtime-gate --ledger-jsonl ...` appends one local gate row only after localhost-only metadata and `--runtime-gate-ack`: it starts no listener, forwards no traffic, and performs no DNS lookup. `context-guard experiments serve local-proxy ...` is the separate forwarding MVP: it requires `--forwarding-gate-ack --once`, a private `--ready-file` nonce handoff, literal loopback bind/target IPs, no hostname DNS targets, nonzero ports, byte/time limits, and credential-free requests; it performs no external forwarding, no CONNECT/TLS proxying, no API-key persistence, and no hosted-savings claim. `--response-sandbox` can store safe UTF-8 response text as a sanitized local artifact receipt and return a compact envelope with redacted rehydration command templates; it does not claim hosted token/cost savings. `--diagnostic-ledger-jsonl` writes one shifted-cost diagnostic row only after a successful forwarded request, with no raw headers/bodies and no hosted-savings evidence. `plan local-proxy-external-forwarding` emits threat-model/allowlist/redaction/provider-evidence design metadata only and still starts no listener, performs no DNS lookup, calls no external service, forwards no traffic, persists no credentials, and does not ship an external proxy forwarding runtime. `experiments enable` records intent only; it does not run those helpers, remove the need for their explicit flags, or permit replacing content without exact receipt/re-expand evidence.
 
 Cross-agent rule snippets are advisory: the target agent may ignore them, so measure actual before/after behavior when you need a savings claim.
 
+## Local MCP adapter
+
+`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.
+
 ## Local test before publishing
 
 From the marketplace repository root:
@@ -178,6 +199,16 @@ Marketplace installation test:
 /plugin install context-guard@context-guard
 ```
 
+### Experimental semantic-GC plan gate
+
+`semantic-gc` is a default-off, deny-only, plan-review gate over a caller-declared graph. Default-off describes registry intent; the explicit plan CLI remains invocable and never enables omission or runtime action. Graph evaluation is suppressed when the complete envelope or topology is ambiguous. Unreachable nodes are review candidates, not proof of semantic irrelevance: omission and runtime action remain unauthorized. Candidate missed-context notes are untrusted. The planner does not read context/artifact content or verify provenance, fallback, providers, or hosted savings. Exit 0 means only `ready_for_plan_review`; it is never delete/omit authority.
+
+context-guard experiments plan semantic-gc --json --context-unit-json '{"schema":"contextguard.semantic-gc-unit.v1","unit_id":"root","references":[],"is_root":true,"protected_zone":false}' --context-unit-json '{"schema":"contextguard.semantic-gc-unit.v1","unit_id":"orphan","references":[],"is_root":false,"protected_zone":false,"content_sha256":"bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb","provenance":{"source_label":"canonical-example","receipt_id":"0123456789abcdef"},"missed_context_note":"A reviewer could lose the orphaned rationale.","exact_fallback_command":"context-guard-artifact get 0123456789abcdef --full"}' --provider-boundary-ack --human-review-ack --protected-zone-policy deny
+
+`static-relevance` is a default-off compiler for bounded caller-supplied static evidence. Missing signals suppress all slices and review ordering; accepted empty edge lists are declarations, not verified observations. Built-in protected-path matches and explicit protected reasons are hard retention vetoes that move evidence first for human review only. This plan-review-only command does not scan or read any repository, does not invoke git, and does not invoke a parser, provider, network, or subprocess. Its deterministic review order does not authorize omission, deletion, deprioritization, replacement, or runtime action.
+
+context-guard experiments plan static-relevance --json --relevance-unit-json '{"schema":"contextguard.static-relevance-unit.v1","unit_id":"src/cli.py::main","path":"src/cli.py","task_anchor":true,"protection_reasons":[],"symbol":{"name":"main","kind":"function","start_line":1,"end_line":40},"symbol_references":[],"dataflow_predecessors":[],"dataflow_successors":[],"git":{"blame_age_days":2,"blame_contributor_count":1,"path_change_count_90d":3}}' --protected-path-policy deny --provider-boundary-ack
+
 ## License
 
 Copyright 2026 jinhongan. Licensed under the Apache License 2.0. See [LICENSE](LICENSE) and [NOTICE](NOTICE).