@ictechgy/context-guard 0.4.4 → 0.4.6

package/docs/benchmark-fixtures/learned-compression-candidate-digest.prompt.example.md

@@ -0,0 +1,21 @@
+Fixture-only candidate prompt for learned-compression experiment setup.
+
+You are reviewing an already-sanitized compressed digest candidate. This is synthetic benchmark input only. No learned compressor, latent helper, embedding model, reranker, or provider call is shipped or invoked by this fixture.
+
+Sanitized evidence only: private paths, endpoints, screenshots, secrets, raw credentials, and unsanitized logs do not belong in this fixture. Protected evidence no semantic rewrite: protected identifiers, constants, hashes, paths, quoted strings, stack frames, JSON keys, code fences, and diff zones must remain exact or receipt-retrievable.
+
+Compressed digest candidate:
+- candidate id: fixture-compression-alpha
+- digest summary: sample_module.py branch returns quoted string `retry` after numeric constant `3` attempts
+- protected evidence preserved exactly: identifier `sample_status`, numeric constant `3`, quoted string `retry`, JSON key `status`, and stack frame label `sample_module:31`
+- omitted protected context: sample_helper.py lines 1:80
+- receipt fallback: fixture-receipt-alpha
+- exact retrieval fallback: context-guard-pack slice --path sample_helper.py --lines 1:80
+
+Task:
+1. Decide whether required evidence is exact or receipt-retrievable.
+2. Identify any protected evidence that would make semantic rewrite unsafe.
+3. State that digest size, byte ratios, and receipt availability are proxy or retrieval evidence only, not hosted API token or cost savings evidence.
+4. State that real comparisons require provider-measured primary token/cost fields on matched successful tasks, plus a failure-rate guardrail, human corrections, and shifted-cost accounting.
+
+This prompt is dry-run-only fixture scaffolding and does not claim hosted API savings.

package/docs/benchmark-fixtures/learned-compression.tasks.example.json

@@ -8,7 +8,11 @@
     "max_budget_usd": 1.0,
     "allowed_tools": [],
     "success_command": "python3 -c \"raise SystemExit('fixture-only placeholder: replace success_command before real benchmark runs')\"",
-    "success_cwd": "."
+    "success_cwd": ".",
+    "variant_prompt_files": {
+      "baseline_uncompressed_fixture": "learned-compression-baseline-context-pack.prompt.example.md",
+      "fixture_only_learned_compression_candidate": "learned-compression-candidate-digest.prompt.example.md"
+    }
   },
   {
     "id": "learned_compression_artifact_digest_fixture",

package/docs/benchmark-fixtures/output-transform-baseline-raw-output.prompt.example.md

@@ -0,0 +1,20 @@
+Fixture-only raw-output prompt for reversible output-transform A/B setup.
+
+You are reviewing an already-sanitized command transcript. Treat this as synthetic benchmark input only.
+
+Raw sanitized command output:
+- command: python3 -m unittest sample_suite
+- status: failed
+- summary: one assertion failed in sample_test_alpha
+- excerpt line 01: expected status ok
+- excerpt line 02: actual status retry
+- excerpt line 03: sanitized stack frame in sample_module
+- excerpt line 04: sanitized assertion message
+- excerpt line 05: sanitized context marker
+
+Task:
+1. Identify the failing command and failing check.
+2. Explain whether the visible raw output is enough to diagnose the synthetic failure.
+3. State that real token or cost comparisons require provider-measured telemetry on matched successful tasks, a failure-rate guardrail, human corrections, and shifted-cost accounting.
+
+This prompt is not shipped benchmark evidence and does not claim hosted API savings.

package/docs/benchmark-fixtures/output-transform-digest-receipt.prompt.example.md

@@ -0,0 +1,23 @@
+Fixture-only digest plus artifact receipt prompt for reversible output-transform A/B setup.
+
+You are reviewing an already-sanitized digest and receipt. Treat this as synthetic benchmark input only.
+
+Digest of sanitized command output:
+- command: python3 -m unittest sample_suite
+- status: failed
+- failure summary: sample_test_alpha expected ok but saw retry
+- omitted sanitized lines: 5
+
+Artifact receipt:
+- artifact id: fixture-artifact-alpha
+- digest id: fixture-digest-alpha
+- exact re-expand command: context-guard-artifact show fixture-artifact-alpha
+- re-expand expectation: retrieves the omitted sanitized lines exactly from a user-supplied local artifact store
+
+Task:
+1. Identify the failing command and failing check.
+2. Describe which exact re-expand step would retrieve the omitted sanitized lines.
+3. State that artifact receipt metadata and byte counts are retrieval or proxy evidence only, not token or cost savings evidence.
+4. State that real comparisons require provider-measured telemetry on matched successful tasks, a failure-rate guardrail, human corrections, and shifted-cost accounting.
+
+This prompt is dry-run-only fixture scaffolding and does not claim hosted API savings.

package/docs/benchmark-fixtures/output-transform.tasks.example.json

@@ -0,0 +1,28 @@
+[
+  {
+    "id": "output_transform_trim_digest_fixture",
+    "prompt": "Fixture-only synthetic reversible output-transform task. Compare a placeholder raw command log with a digest plus artifact receipt and answer whether omitted sanitized lines can be exactly re-expanded. This fixture does not run a provider, trim command output, or fetch artifacts; future real runs must supply sanitized raw and digest evidence, artifact receipt metadata, provider-measured token/cost telemetry, matched successful tasks, failure-rate guardrail, human corrections, and shifted-cost accounting.",
+    "model": "sonnet",
+    "effort": "medium",
+    "max_turns": 3,
+    "max_budget_usd": 1.0,
+    "allowed_tools": [],
+    "success_command": "python3 -c \"raise SystemExit('fixture-only placeholder: replace success_command before real benchmark runs')\"",
+    "success_cwd": ".",
+    "variant_prompt_files": {
+      "baseline_raw_output_fixture": "output-transform-baseline-raw-output.prompt.example.md",
+      "fixture_only_digest_artifact_receipt": "output-transform-digest-receipt.prompt.example.md"
+    }
+  },
+  {
+    "id": "output_transform_failure_summary_fixture",
+    "prompt": "Fixture-only synthetic reversible output-transform task. Given a placeholder failure summary and a receipt-backed sanitized output handle, identify the failing command and describe which exact re-expand step would retrieve the omitted context. This fixture is dry-run-only until prompts, success checks, provider-measured primary token/cost fields, human corrections, and shifted-cost accounting are supplied for matched successful tasks.",
+    "model": "sonnet",
+    "effort": "medium",
+    "max_turns": 3,
+    "max_budget_usd": 1.0,
+    "allowed_tools": [],
+    "success_command": "python3 -c \"raise SystemExit('fixture-only placeholder: replace success_command before real benchmark runs')\"",
+    "success_cwd": "."
+  }
+]

package/docs/benchmark-fixtures/output-transform.variants.example.json

@@ -0,0 +1,10 @@
+[
+  {
+    "name": "baseline_raw_output_fixture",
+    "extra_args": []
+  },
+  {
+    "name": "fixture_only_digest_artifact_receipt",
+    "extra_args": []
+  }
+]

package/docs/benchmark-fixtures/visual-ocr-cropped-ocr.prompt.example.md

@@ -0,0 +1,22 @@
+Fixture-only cropped/OCR prompt for multimodal crop/OCR experiment setup.
+
+You are reviewing sanitized textual cropped/OCR-derived evidence only. This fixture contains no screenshot, image file, image URL, private path, endpoint, crop helper, OCR helper, visual-token helper, or provider call.
+
+Cropped or OCR-derived evidence:
+- original image dimensions telemetry: width 1200, height 800
+- crop area telemetry: x 80, y 120, width 640, height 360
+- visible area: checkout form region with validation text `Card number required`
+- OCR text: `Card number required`; `Continue`
+- OCR confidence telemetry: 0.96 for validation text; 0.92 for navigation label
+- OCR error notes: footer notice omitted by crop; decorative icon ignored
+- omitted context: footer notice `Sandbox order` and page-wide navigation are not visible in the crop
+- missed-context guardrail: if the answer depends on omitted context, fall back to full visual evidence before judging success
+- full visual fallback: rerun with baseline_full_visual_fixture evidence when OCR confidence is low, crop area excludes required context, or human correction is needed
+
+Task:
+1. Identify the navigation control associated with the visible validation error.
+2. List any missed or omitted context that could change the answer.
+3. State that crop area, OCR text, OCR confidence, and byte counts are proxy or telemetry evidence only, not hosted API token or cost savings evidence.
+4. State that real comparisons require provider-measured image/text token or cost fields when available, matched successful tasks, failure-rate guardrail, human corrections, and shifted-cost accounting.
+
+This prompt is dry-run-only fixture scaffolding and does not claim hosted API savings.

package/docs/benchmark-fixtures/visual-ocr-full-visual.prompt.example.md

@@ -0,0 +1,19 @@
+Fixture-only full visual prompt for multimodal crop/OCR experiment setup.
+
+You are reviewing sanitized textual visual evidence only. This fixture contains no screenshot, image file, image URL, private path, endpoint, crop helper, OCR helper, visual-token helper, or provider call.
+
+Full visual evidence:
+- image dimensions telemetry: width 1200, height 800
+- visible area: full page region
+- checkout form context: navigation button label `Continue`, validation text `Card number required`, footer notice `Sandbox order`
+- missed context risk: none for this baseline because the full visual description is present
+- OCR confidence telemetry: not applicable for full visual baseline
+- OCR error notes: not applicable for full visual baseline
+
+Task:
+1. Identify the navigation control associated with the visible validation error.
+2. State what evidence would need to remain visible if a cropped or OCR-derived variant is used.
+3. State that image dimensions and visible area are telemetry only, not hosted API token or cost savings evidence.
+4. State that real comparisons require provider-measured image/text token or cost fields when available, matched successful tasks, failure-rate guardrail, human corrections, and shifted-cost accounting.
+
+This prompt is dry-run-only fixture scaffolding and does not claim hosted API savings.

package/docs/benchmark-fixtures/visual-ocr.tasks.example.json

@@ -8,7 +8,11 @@
     "max_budget_usd": 1.0,
     "allowed_tools": [],
     "success_command": "python3 -c \"raise SystemExit('fixture-only placeholder: replace success_command before real benchmark runs')\"",
-    "success_cwd": "."
+    "success_cwd": ".",
+    "variant_prompt_files": {
+      "baseline_full_visual_fixture": "visual-ocr-full-visual.prompt.example.md",
+      "fixture_only_cropped_or_ocr_evidence": "visual-ocr-cropped-ocr.prompt.example.md"
+    }
   },
   {
     "id": "visual_ocr_table_status_fixture",

package/docs/benchmark-workflow-examples.md

@@ -17,6 +17,7 @@ Use them to decide what evidence a workflow has and what it does **not** prove:
 | [`benchmark-workflows/context-pack-byte-proxy.example.json`](benchmark-workflows/context-pack-byte-proxy.example.json) | `context-guard-pack auto` can reduce selected local bytes and inferred token proxies. | No hosted API token-savings claim because primary provider token fields are unavailable. |
 | [`benchmark-workflows/provider-cache-telemetry.example.json`](benchmark-workflows/provider-cache-telemetry.example.json) | Cache-layout diagnostics can coincide with observed provider cached-token telemetry. | Provider-cache telemetry is not proof that ContextGuard reduced prompt tokens or cost. |
 | [`benchmark-workflows/measured-token-workflow.example.json`](benchmark-workflows/measured-token-workflow.example.json) | A matched successful task pair with measured primary tokens may expose `token_savings_pct`. | The percentage is sample report data only, not a general savings promise; real claims require your own matched successful task runs and quality gates. |
+| [`benchmark-workflows/self-hosted-metrics-ledger.example.jsonl`](benchmark-workflows/self-hosted-metrics-ledger.example.jsonl) | A run-evidence JSONL row can carry explicit local/model-server latency, peak-memory, and quality sidecar metrics. | Self-hosted metrics are not hosted API token/cost telemetry and do not change report savings math. |
 
 ## How to use the examples
 
@@ -24,6 +25,7 @@ Use them to decide what evidence a workflow has and what it does **not** prove:
 2. Compare your report's `claim_status`, `summary_by_variant`, and `comparisons[].quality_gate` to the examples.
 3. Treat `comparisons[].quality_gate != "pass"` as a warning to inspect failures, correction burden, and unmatched tasks before discussing savings.
 4. Keep byte-proxy, provider-cache, wall-time, and shifted-cost evidence in separate language from provider-measured token/cost claims. Provider-cache telemetry is not independent savings proof.
+5. Keep self-hosted local/model-server latency, memory, and quality metrics in the run-evidence ledger sidecar; do not fold them into hosted API token/cost savings claims unless provider-measured matched-task evidence separately supports that claim.
 
 ## Safe wording
 
@@ -35,6 +37,8 @@ Avoid language like:
 
 > ContextGuard guarantees this workflow will save tokens or cost.
 
-The fixtures intentionally use full `context-guard-bench-report-v1` shapes so tests can catch schema drift and overclaim wording.
+The `.example.json` fixtures intentionally use full `context-guard-bench-report-v1` shapes so tests can catch schema drift and overclaim wording.
 
-For task/variant starter fixtures rather than full report-shape examples, see [`experimental-benchmark-fixtures.md`](experimental-benchmark-fixtures.md). Those files are fixture-only and synthetic dry-run-only starters until users replace the placeholder prompts and success checks; they are not shipped OCR, visual-token, or learned-compression runtime features, and real claims still require provider-measured matched successful tasks plus failure-rate, correction, and shifted-cost guardrails.
+The self-hosted metrics example is a JSONL run-evidence sidecar, not a full report shape. Its fields are additive ledger evidence only: `latency_ms`, `peak_memory_mb`, and normalized `quality_score` describe local/model-server behavior and leave hosted API report calculations unchanged.
+
+For task/variant starter fixtures rather than full report-shape examples, see [`experimental-benchmark-fixtures.md`](experimental-benchmark-fixtures.md). Those files are fixture-only and synthetic dry-run-only starters until users replace the placeholder prompts and success checks; they are not shipped OCR, visual-token, learned-compression, or output-transform benchmark results, and real claims still require provider-measured matched successful tasks plus failure-rate, correction, and shifted-cost guardrails.

package/docs/benchmark-workflows/self-hosted-metrics-ledger.example.jsonl

@@ -0,0 +1 @@
+{"schema_version":"contextguard.bench.run-evidence.v1","task_id":"self-hosted-demo","variant":"local-cache-reuse","success":true,"primary_tokens_measured":false,"primary_tokens":0,"primary_cost_measured":false,"primary_cost_usd":0.0,"external_tokens_measured":false,"external_tokens":0,"external_cost_measured":false,"external_cost_usd":0.0,"total_cost_with_shift_usd":null,"wall_time_seconds":0.0,"measurement_availability":{"primary_tokens":false,"primary_cost":false,"external_tokens":false,"external_cost":false,"shifted_cost":false,"provider_cache":false,"byte_metrics":false,"wall_time":true,"self_hosted_metrics":true},"self_hosted_metrics":{"schema_version":"contextguard.bench.self-hosted-metrics.v1","source":"explicit_provider_payload.self_hosted_metrics","metrics":{"latency_ms":842.5,"peak_memory_mb":14336.0,"quality_score":0.98},"labels":{"model_server":"local test server","optimization":"prefix cache reuse","quality_metric":"golden task pass rate"},"measurement_availability":{"latency_ms":true,"peak_memory_mb":true,"quality_score":true},"claim_boundary":{"id":"self_hosted_metrics_only_not_hosted_api_token_or_cost_savings","hosted_api_token_savings_claim_allowed":false,"hosted_api_cost_savings_claim_allowed":false,"requires_provider_measured_matched_tasks_for_hosted_claims":true,"reason":"Self-hosted local/model-server latency, memory, and quality metrics are not hosted API token or cost telemetry."}},"proxy_metrics":{"byte_metrics_observed":false,"token_proxy":"chars_div_4","bytes_per_token":4,"claim_boundary":"proxy_only_not_hosted_token_savings"},"notes":"Synthetic JSONL shape only; make hosted API savings claims only from provider-measured matched successful task evidence."}

package/docs/experimental-benchmark-fixtures.md

@@ -1,6 +1,6 @@
 # Experimental benchmark fixtures
 
-These fixtures are **fixture-only** starter scaffolds for future visual/OCR and learned-compression experiments. They are **synthetic**, package-visible examples for `context-guard-bench` task and variant shapes; they are **not a shipped runtime feature**, not an OCR/compression implementation, and not a hosted API savings claim.
+These fixtures are **fixture-only** starter scaffolds for future visual/OCR, learned-compression, and reversible output-transform experiments. They are **synthetic**, package-visible examples for `context-guard-bench` task and variant shapes; they are **not shipped benchmark results**, not OCR/compression implementations, and not hosted API savings claims.
 
 Use them when designing an experiment that starts from ContextGuard's existing benchmark discipline:
 
@@ -12,20 +12,31 @@ Use them when designing an experiment that starts from ContextGuard's existing b
 5. Treat byte counts, image dimensions, OCR confidence, and local compressor ratios as proxy evidence. Real token/cost claims require **provider-measured** primary token/cost fields on both sides.
 6. Keep private screenshots, raw secrets, and external service endpoints out of fixture files.
 
+## Runner-native variant prompt files
+
+`context-guard-bench` supports optional file-backed `variant_prompt_files` in task fixtures. The map is keyed by variant name and lets a single logical task swap sanitized prompt evidence per variant, for example a baseline raw-output prompt versus a digest plus artifact receipt prompt. Prompt files are resolved relative to the task JSON, must be relative paths, and are read with the same no-follow/symlink-safe posture as task and variant fixtures.
+
+This runner-native swap only proves command shape and prompt selection until the user supplies real sanitized tasks, success checks, and provider telemetry. It does **not** make dry-run output, artifact receipts, byte counts, or digest metadata into token/cost savings evidence. For real non-dry-run output-transform experiments, keep task IDs matched across baseline and digest variants and require provider-measured primary token/cost fields on matched successful tasks before making any comparison claim.
+
 ## Included fixture sets
 
 | Fixture set | Task file | Variant file | Intended future experiment |
 | --- | --- | --- | --- |
-| Visual/OCR evidence | [`benchmark-fixtures/visual-ocr.tasks.example.json`](benchmark-fixtures/visual-ocr.tasks.example.json) | [`benchmark-fixtures/visual-ocr.variants.example.json`](benchmark-fixtures/visual-ocr.variants.example.json) | Compare full visual evidence against cropped or OCR-derived evidence after the user supplies sanitized artifacts and provider telemetry. |
-| Learned compression | [`benchmark-fixtures/learned-compression.tasks.example.json`](benchmark-fixtures/learned-compression.tasks.example.json) | [`benchmark-fixtures/learned-compression.variants.example.json`](benchmark-fixtures/learned-compression.variants.example.json) | Compare baseline context packs or artifact digests against a future learned-compression candidate after quality gates and shifted costs are measured. |
+| Visual/OCR evidence | [`benchmark-fixtures/visual-ocr.tasks.example.json`](benchmark-fixtures/visual-ocr.tasks.example.json) | [`benchmark-fixtures/visual-ocr.variants.example.json`](benchmark-fixtures/visual-ocr.variants.example.json) | Compare full visual evidence against cropped or OCR-derived evidence after the user supplies sanitized textual evidence, missed-context notes, crop/OCR telemetry, and provider telemetry. |
+| Learned compression | [`benchmark-fixtures/learned-compression.tasks.example.json`](benchmark-fixtures/learned-compression.tasks.example.json) | [`benchmark-fixtures/learned-compression.variants.example.json`](benchmark-fixtures/learned-compression.variants.example.json) | Compare sanitized baseline context packs against a fixture-only compressed digest candidate after exact retrieval or receipt fallback, quality gates, and shifted costs are measured. |
+| Reversible output transform | [`benchmark-fixtures/output-transform.tasks.example.json`](benchmark-fixtures/output-transform.tasks.example.json) | [`benchmark-fixtures/output-transform.variants.example.json`](benchmark-fixtures/output-transform.variants.example.json) | Compare raw sanitized command output against a digest plus artifact receipt after variant prompt files, success checks, and provider telemetry are supplied. |
 
 ## Visual/OCR fixture notes
 
-The visual/OCR fixtures describe placeholder evidence only. They do not crop images, run OCR, prune visual tokens, or call a model. Future experiments should record image dimensions, crop area, OCR confidence/error notes, provider image/text token telemetry when available, task success, corrections, and any external/local processing cost.
+The visual/OCR fixtures describe sanitized textual visual evidence only and now demonstrate `variant_prompt_files` for full visual evidence versus cropped/OCR-derived evidence. They do not include image assets, crop images, run OCR, prune visual tokens, or call a model. Future experiments should record image dimensions, crop area, visible area, omitted or missed context, OCR confidence/error notes, full visual fallback conditions, provider image/text token telemetry when available, task success, corrections, and any external/local processing cost.
 
 ## Learned-compression fixture notes
 
-The learned-compression fixtures describe already-sanitized context-pack or artifact-digest comparisons. They do not invoke LLMLingua-style, gist-token, latent-context, or reranking implementations. Future experiments should preserve exact retrieval for lossy transforms where possible and record bytes before/after, primary provider tokens, cost, success, corrections, compressor latency, and external cost.
+The learned-compression fixtures describe already-sanitized context-pack or artifact-digest comparisons and now demonstrate `variant_prompt_files` for baseline context-pack evidence versus a fixture-only compressed digest candidate. They do not invoke LLMLingua-style, gist-token, latent-context, embedding, or reranking implementations. Future experiments must follow a sanitized evidence only rule, keep protected evidence exact or receipt-retrievable, forbid semantic rewrites of identifiers, numeric constants, hashes, paths, quoted strings, stack frames, JSON keys, code fences, and diff zones, and record bytes before/after, primary provider tokens, cost, success, corrections, compressor latency, and external cost.
+
+## Reversible output-transform fixture notes
+
+The output-transform fixtures describe already-sanitized command output comparisons and now demonstrate `variant_prompt_files` for raw sanitized output versus digest plus artifact receipt prompt evidence. They do not execute `context-guard-trim-output`, store artifacts, call `context-guard-artifact`, or invoke a provider. Future experiments should compare raw sanitized output against `--digest` output plus an `--artifact-receipt`, verify the receipt's exact re-expand command retrieves the omitted sanitized lines, and record bytes before/after, primary provider tokens, cost, success, corrections, artifact-store usage, and any external/local processing cost.
 
 ## Safe wording
 
@@ -33,4 +44,4 @@ Use language like:
 
 > This synthetic fixture validates benchmark task/variant shape only. A real claim needs provider-measured token/cost data for matched successful baseline and variant tasks, plus failure-rate, correction, and shifted-cost guardrails.
 
-Avoid language that presents dry-run output, bytes saved, OCR text, or compressor ratios as hosted API token/cost savings evidence.
+Avoid language that presents dry-run output, bytes saved, OCR text, artifact receipts, exact re-expand handles, or compressor ratios as hosted API token/cost savings evidence.

package/docs/mac-visibility-feasibility-schema.md

@@ -0,0 +1,62 @@
+# macOS visibility feasibility contract
+
+`context-guard-audit --feasibility-json` emits a local, pre-GUI contract for future macOS-visible surfaces such as a menu-bar app, xbar item, Raycast command, or SwiftUI prototype. It is a transcript-scan contract, not a GUI implementation and not a live daemon.
+
+The full feasibility envelope is versioned as `contextguard.metric-feasibility.v1.3`. The macOS binding/index inside that envelope is the top-level `mac_visibility` object with nested `schema_version: contextguard.mac-visibility.v1`.
+
+## Contract boundary
+
+- `mac_visibility` is a thin index over stable top-level feasibility fields. It does not recompute totals and does not read diagnostic `summary`.
+- GUI or menu-bar consumers should bind only to fields listed in `consumer_contract.stable_top_level_fields` and `mac_visibility.bind_to_top_level_fields`.
+- `summary` is diagnostic/backward-compatible payload only. It may be shown in a debug panel, but it must not drive primary cards.
+- Historical transcript scans do not include live context-window state. Context and headroom cards stay `missing` until a future surface provides `live_statusline_snapshot`.
+- Values are local transcript observations. They are not invoice-grade billing records, do not prove provider cache hits, and do not guarantee token or cost savings.
+
+## Stable `mac_visibility` keys
+
+| Key | Meaning |
+| --- | --- |
+| `schema_version` | Nested contract version: `contextguard.mac-visibility.v1`. |
+| `surface_kind` | Local surface family; currently `local_macos_visibility_contract`. |
+| `readiness.status` | One of `ready`, `partial`, or `missing`, derived from token availability and scan integrity. |
+| `bind_to_top_level_fields` | Stable top-level fields primary consumers may use. |
+| `diagnostic_only_fields` | Fields that must not drive primary UI; currently `summary`. |
+| `primary_cards` | Ordered card descriptors with `id`, `title`, `status`, and `binding_paths`. |
+| `missing_live_observations` | Required live observations that transcript scans cannot provide. |
+| `claim_boundaries` | Copy-safe caveats for UI labels and docs. |
+| `redaction_required` | Always `true` for default GUI/menu-bar presentation. |
+
+## Card IDs and binding paths
+
+`primary_cards[*].binding_paths` use dotted paths inside the feasibility envelope. Current card IDs are:
+
+1. `source_freshness` → `source_kind`, `source_freshness.status`, `source_freshness.generated_at`
+2. `scan_integrity` → scan completeness and skipped counts
+3. `token_totals` → `totals.total_tokens` and `totals.tokens.*`
+4. `cache_reuse` → `totals.cache_read_share`, `totals.cache_reuse_ratio`, `metric_availability.cache`
+5. `observed_cost` → `totals.cost_usd_observed`, `metric_availability.cost`
+6. `context_availability` → `context_availability`, `metric_availability.context`
+7. `headroom_availability` → `headroom_availability`, `cache_diagnostics.headroom_diagnostics`
+8. `cache_layout_advice` → `cache_layout_advice`, `cache_friendliness`, `cache_diagnostics.dynamic_prefix_breakers`
+
+When a card includes `required_observation: live_statusline_snapshot`, consumers should show an unavailable or setup state rather than treating the value as zero.
+
+## Example
+
+See [`mac-visibility-feasibility.example.json`](mac-visibility-feasibility.example.json) for an abridged feasibility envelope. It keeps `summary` out of primary bindings and demonstrates the missing live context/headroom boundary.
+
+## Verification guidance
+
+For a local fixture:
+
+```bash
+context-guard-audit ./fixtures/transcripts --feasibility-json --recommend
+```
+
+Then verify:
+
+- `schema_version == "contextguard.metric-feasibility.v1.3"`
+- `consumer_contract.stable_top_level_fields` contains `mac_visibility`
+- `mac_visibility.diagnostic_only_fields` contains `summary`
+- no `primary_cards[*].binding_paths` entry starts with `summary`
+- `missing_live_observations[*].required_observation` names `live_statusline_snapshot` when context/headroom are missing

package/docs/mac-visibility-feasibility.example.json

@@ -0,0 +1,130 @@
+{
+  "schema_version": "contextguard.metric-feasibility.v1.3",
+  "producer": "context-guard-audit",
+  "generated_at": "2026-06-08T12:00:00Z",
+  "consumer_contract": {
+    "stable_top_level_fields": [
+      "schema_version",
+      "producer",
+      "generated_at",
+      "source_kind",
+      "source_freshness",
+      "scan_integrity",
+      "metric_availability",
+      "metric_caveats",
+      "redaction_mode",
+      "context_availability",
+      "headroom_availability",
+      "cache_friendliness",
+      "cache_diagnostics",
+      "cache_layout_advice",
+      "mac_visibility",
+      "totals"
+    ],
+    "diagnostic_fields": ["summary"],
+    "summary_contract": "summary is the legacy audit JSON payload for diagnostics and backward compatibility; new GUI prototypes should bind to stable top-level feasibility fields first."
+  },
+  "source_kind": "historical_transcript_scan",
+  "source_freshness": {
+    "status": "snapshot_at_scan_time",
+    "live": false,
+    "generated_at": "2026-06-08T12:00:00Z",
+    "description": "Local transcript files were scanned when this report was generated; this is not a live statusline snapshot."
+  },
+  "scan_integrity": {
+    "status": "complete",
+    "files_scanned": 1,
+    "records_scanned": 1,
+    "skipped_files": 0,
+    "skipped_records": 0,
+    "parse_error_count": 0,
+    "complete": true
+  },
+  "metric_availability": {
+    "tokens": {"status": "available", "present_fields": {"input": 1, "output": 1, "cache_read": 1, "cache_creation": 1}, "evidence": "observed"},
+    "cache": {"status": "available", "present_fields": {"cache_read": 1, "cache_creation": 1}, "zero_values_observed": {"cache_read": false, "cache_creation": false}, "evidence": "observed"},
+    "cost": {"status": "available", "present_count": 1, "observed_cost_usd": 0.1234, "evidence": "observed"},
+    "context": {"status": "missing", "evidence": "unavailable", "reason": "Transcript scans do not include live Claude Code context_window data. Pass a live statusline snapshot in a future surface to populate context availability."},
+    "headroom": {"status": "missing", "evidence": "unavailable", "reason": "Transcript scans do not carry live context-window or remaining-token data, so context headroom cannot be observed or conservatively inferred from history alone.", "observable_via": "live_statusline_snapshot"}
+  },
+  "metric_caveats": [
+    "Values are observed from local Claude Code transcript JSON/JSONL fields and are not official billing records.",
+    "cache-read share is cache_read / (input + cache_read + cache_creation), not a provider billing hit-rate."
+  ],
+  "redaction_mode": {
+    "paths": "basename_plus_stable_hash_by_default",
+    "commands": "command_category_plus_stable_hash_by_default",
+    "secret_like_values": "pattern_redacted",
+    "raw_path_and_command_flags": ["--show-paths", "--show-commands"]
+  },
+  "context_availability": {"status": "missing", "evidence": "unavailable", "reason": "Transcript scans do not include live Claude Code context_window data. Pass a live statusline snapshot in a future surface to populate context availability."},
+  "headroom_availability": {"status": "missing", "evidence": "unavailable", "observable_via": "live_statusline_snapshot", "reason": "Transcript scans do not carry live context-window or remaining-token data, so context headroom cannot be observed or conservatively inferred from history alone."},
+  "cache_friendliness": {"status": "partial", "confidence": "partial", "evidence": "observed", "heuristic": true},
+  "cache_diagnostics": {
+    "schema_version": "contextguard.cache-diagnostics.v1",
+    "status": "partial",
+    "confidence": "hypothesis",
+    "evidence": "inferred",
+    "heuristic": true,
+    "dynamic_prefix_breakers": [],
+    "headroom_diagnostics": {"status": "missing", "evidence": "unavailable", "observable_via": "live_statusline_snapshot", "required_observation": "live_statusline_snapshot", "historical_total_tokens_are_not_headroom": true}
+  },
+  "cache_layout_advice": {
+    "schema_version": "contextguard.cache-layout-advice.v1",
+    "status": "partial",
+    "confidence": "partial",
+    "priority": "P1",
+    "observed_issue": "long_session_accumulation"
+  },
+  "mac_visibility": {
+    "schema_version": "contextguard.mac-visibility.v1",
+    "surface_kind": "local_macos_visibility_contract",
+    "readiness": {
+      "status": "ready",
+      "reason": "Transcript token totals are available and the scan completed within configured limits."
+    },
+    "bind_to_top_level_fields": [
+      "source_kind",
+      "source_freshness",
+      "scan_integrity",
+      "metric_availability",
+      "metric_caveats",
+      "redaction_mode",
+      "context_availability",
+      "headroom_availability",
+      "cache_friendliness",
+      "cache_diagnostics",
+      "cache_layout_advice",
+      "totals"
+    ],
+    "diagnostic_only_fields": ["summary"],
+    "primary_cards": [
+      {"id": "source_freshness", "title": "Source freshness", "status": "available", "binding_paths": ["source_kind", "source_freshness.status", "source_freshness.generated_at"]},
+      {"id": "scan_integrity", "title": "Scan integrity", "status": "complete", "binding_paths": ["scan_integrity.status", "scan_integrity.files_scanned", "scan_integrity.records_scanned", "scan_integrity.skipped_files", "scan_integrity.skipped_records"]},
+      {"id": "token_totals", "title": "Token totals", "status": "available", "binding_paths": ["totals.total_tokens", "totals.tokens.input", "totals.tokens.output", "totals.tokens.cache_read", "totals.tokens.cache_creation"]},
+      {"id": "cache_reuse", "title": "Cache-read share and reuse ratio", "status": "available", "binding_paths": ["totals.cache_read_share", "totals.cache_reuse_ratio", "metric_availability.cache"]},
+      {"id": "observed_cost", "title": "Observed transcript cost", "status": "available", "binding_paths": ["totals.cost_usd_observed", "metric_availability.cost"]},
+      {"id": "context_availability", "title": "Context availability", "status": "missing", "binding_paths": ["context_availability", "metric_availability.context"], "required_observation": "live_statusline_snapshot"},
+      {"id": "headroom_availability", "title": "Headroom availability", "status": "missing", "binding_paths": ["headroom_availability", "cache_diagnostics.headroom_diagnostics"], "required_observation": "live_statusline_snapshot"},
+      {"id": "cache_layout_advice", "title": "Cache layout advice", "status": "partial", "binding_paths": ["cache_layout_advice", "cache_friendliness", "cache_diagnostics.dynamic_prefix_breakers"]}
+    ],
+    "missing_live_observations": [
+      {"id": "live_context_window", "required_observation": "live_statusline_snapshot", "affects": ["context_availability", "metric_availability.context"], "reason": "Historical transcript scans do not include live Claude Code context_window data."},
+      {"id": "live_headroom", "required_observation": "live_statusline_snapshot", "affects": ["headroom_availability", "cache_diagnostics.headroom_diagnostics"], "reason": "Historical transcript totals are not remaining-token or live headroom observations."}
+    ],
+    "claim_boundaries": [
+      "Local transcript observations are not invoice-grade billing records.",
+      "Provider cache fields are telemetry, not ContextGuard-caused token reduction and do not prove provider cache hits.",
+      "Historical transcript totals do not infer live context headroom or remaining tokens.",
+      "This contract does not guarantee token or cost savings."
+    ],
+    "redaction_required": true
+  },
+  "totals": {
+    "total_tokens": 1150,
+    "tokens": {"input": 100, "output": 50, "cache_read": 800, "cache_creation": 200},
+    "cost_usd_observed": 0.1234,
+    "cache_read_share": 0.7272727272727273,
+    "cache_reuse_ratio": 4.0
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ictechgy/context-guard",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "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",
@@ -55,9 +55,13 @@
     "docs/cache-diagnostics-schema.md",
     "docs/cache-diagnostics.schema.json",
     "docs/cache-diagnostics.example.json",
+    "docs/mac-visibility-feasibility-schema.md",
+    "docs/mac-visibility-feasibility.example.json",
     "docs/benchmark-workflows/*.example.json",
+    "docs/benchmark-workflows/*.example.jsonl",
     "docs/benchmark-workflow-examples.md",
     "docs/benchmark-fixtures/*.example.json",
+    "docs/benchmark-fixtures/*.prompt.example.md",
     "docs/experimental-benchmark-fixtures.md",
     "packaging/homebrew/context-guard.rb.template"
   ],

package/packaging/homebrew/context-guard.rb.template

@@ -5,7 +5,7 @@ class ContextGuard < Formula
 
   desc "Local-first context guardrails for AI coding agents"
   homepage "https://github.com/ictechgy/context-guard"
-  url "https://github.com/ictechgy/context-guard/archive/refs/tags/v0.4.4.tar.gz"
+  url "https://github.com/ictechgy/context-guard/archive/refs/tags/v0.4.6.tar.gz"
   sha256 "REPLACE_WITH_RELEASE_TARBALL_SHA256"
   license "Apache-2.0"
 

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

@@ -37,5 +37,5 @@
     "gated-experiments",
     "future-roadmap"
   ],
-  "version": "0.4.4"
+  "version": "0.4.6"
 }

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

@@ -97,7 +97,7 @@ context-guard-statusline-merged
 - **상태표시줄**은 모델, 컨텍스트, 비용 신호를 짧게 보여주고, 대화 기록 데이터가 있으면 캐시 읽기와 캐시 재사용 신호도 함께 표시합니다.
 - **대화 기록 감사**는 usage/cost/cache bucket을 집계하고, 토큰 집중 지점, `cache_friendliness` 프롬프트 배치 신호, `cache_layout_advice` 확인/실험 우선순위를 제한된 가림 처리된 segment hash로 보고합니다. 원문 프롬프트는 출력하지 않습니다.
 - **반복 실패 알림**은 Bash 실패가 반복될 때 같은 경로를 계속 재시도하지 않고 전략을 바꾸도록 안내합니다.
-- **벤치마크 헬퍼**는 기준/변형 실행을 대응해 실제 토큰·비용 필드, 별도의 바이트 감소 간접 증거, 진단용 `wall_time_seconds`, `provider_cached_tokens`, provider-cache 사용 가능성 텔레메트리로 기록합니다.
+- **벤치마크 헬퍼**는 기준/변형 실행을 대응해 실제 토큰·비용 필드, 별도의 바이트 감소 간접 증거, 진단용 `wall_time_seconds`, `provider_cached_tokens`, provider-cache 사용 가능성 텔레메트리, 파일 기반 `variant_prompt_files`, 선택적 run별 `self_hosted_metrics` JSONL ledger sidecar를 기록합니다. 이 sidecar는 hosted API 절감 주장에 합치지 않습니다.
 
 비용 가드의 로컬 HMAC 키는 기본적으로 `.context-guard/cost-ledger/hmac.key`에 자동 생성됩니다. 관리자가 직접 주입하는 경우 파일에는 필수 padding을 포함한 canonical URL-safe base64 32바이트 키만 정확히 들어 있어야 하며, trailing newline이나 공백은 허용하지 않습니다. 리포트는 키와 원문 프롬프트를 출력하지 않고, 로컬 ledger는 Anthropic/provider prompt cache를 대체하지 않습니다.
 

package/plugins/context-guard/README.md

@@ -103,7 +103,7 @@ context-guard-statusline-merged
 - **Statusline** displays compact model/context/cost signals and, when transcript data is available, cache-read and cache-reuse signals.
 - **Transcript audit** aggregates usage/cost/cache buckets, flags likely token hotspots, and exposes `cache_friendliness`, additive [`cache_diagnostics`](https://github.com/ictechgy/context-guard/blob/main/docs/cache-diagnostics-schema.md), and `cache_layout_advice` experiment priorities from bounded usage fields, timestamped cache telemetry records, and redacted segment hashes without printing raw prompt text or claiming provider-cache savings.
 - **Repeated-failure nudge** warns after repeated Bash failures so the agent switches strategy instead of retrying the same context-heavy path.
-- **Benchmark helper** records matched baseline/variant runs with real token and cost fields, separate byte-reduction proxy evidence, diagnostic `wall_time_seconds`, `provider_cached_tokens`, and provider-cache availability telemetry.
+- **Benchmark helper** records matched baseline/variant runs with real token and cost fields, separate byte-reduction proxy evidence, diagnostic `wall_time_seconds`, `provider_cached_tokens`, provider-cache availability telemetry, file-backed `variant_prompt_files`, and optional per-run `self_hosted_metrics` JSONL ledger sidecars that stay out of hosted API savings claims.
 
 Cost guard creates its local HMAC key automatically at `.context-guard/cost-ledger/hmac.key`. If you provision that file yourself, it must contain exactly one canonical URL-safe base64 32-byte key with required padding and no trailing newline or whitespace. Reports never emit the key or raw prompt text, and the local ledger does not replace Anthropic/provider prompt caching.