@ictechgy/context-guard 0.4.4 → 0.4.5

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.5",
   "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/plugins/context-guard/.claude-plugin/plugin.json

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

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.
 

package/plugins/context-guard/bin/context-guard-audit

@@ -46,7 +46,8 @@ COST_KEYS = ("total_cost_usd", "cost_usd", "costUSD")
 MODEL_KEYS = ("model", "model_id", "modelId")
 QUERY_SOURCE_KEYS = ("query_source", "querySource")
 TIMESTAMP_KEYS = ("timestamp", "created_at", "createdAt", "time", "ts")
-FEASIBILITY_SCHEMA_VERSION = "contextguard.metric-feasibility.v1.2"
+FEASIBILITY_SCHEMA_VERSION = "contextguard.metric-feasibility.v1.3"
+MAC_VISIBILITY_SCHEMA_VERSION = "contextguard.mac-visibility.v1"
 FEASIBILITY_PRODUCER = "context-guard-audit"
 CACHE_DIAGNOSTICS_SCHEMA_VERSION = "contextguard.cache-diagnostics.v1"
 CACHE_LAYOUT_ADVICE_SCHEMA_VERSION = "contextguard.cache-layout-advice.v1"
@@ -1635,6 +1636,168 @@ def build_metric_caveats(summary: UsageSummary) -> list[str]:
     return caveats
 
 
+def _mac_card(
+    card_id: str,
+    title: str,
+    status: str,
+    binding_paths: list[str],
+    *,
+    required_observation: str | None = None,
+) -> dict[str, Any]:
+    card: dict[str, Any] = {
+        "id": card_id,
+        "title": title,
+        "status": status,
+        "binding_paths": binding_paths,
+    }
+    if required_observation:
+        card["required_observation"] = required_observation
+    return card
+
+
+def build_mac_visibility_contract(
+    *,
+    availability: dict[str, Any],
+    integrity: dict[str, Any],
+    cache_layout_advice: dict[str, Any],
+) -> dict[str, Any]:
+    """Build the pre-GUI macOS visibility binding contract.
+
+    This is intentionally a thin index over already-emitted stable feasibility
+    fields. It does not recompute metrics, read diagnostic summary data, or infer
+    live context/headroom from historical transcript totals.
+    """
+    token_status = str((availability.get("tokens") or {}).get("status", "missing"))
+    scan_status = str(integrity.get("status", "partial"))
+    if token_status == "available" and scan_status == "complete":
+        readiness_status = "ready"
+        readiness_reason = "Transcript token totals are available and the scan completed within configured limits."
+    elif token_status in {"available", "partial"}:
+        readiness_status = "partial"
+        readiness_reason = "Some stable fields can be shown, but scan integrity or metric availability is partial."
+    else:
+        readiness_status = "missing"
+        readiness_reason = "Token totals are missing from the transcript scan; show setup or unavailable state."
+
+    context_status = str((availability.get("context") or {}).get("status", "missing"))
+    headroom_status = str((availability.get("headroom") or {}).get("status", "missing"))
+    cache_status = str((availability.get("cache") or {}).get("status", "missing"))
+    cost_status = str((availability.get("cost") or {}).get("status", "missing"))
+    advice_status = str(cache_layout_advice.get("status", "missing"))
+
+    missing_live_observations: list[dict[str, Any]] = []
+    if context_status == "missing":
+        missing_live_observations.append({
+            "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.",
+        })
+    if headroom_status == "missing":
+        missing_live_observations.append({
+            "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.",
+        })
+
+    return {
+        "schema_version": MAC_VISIBILITY_SCHEMA_VERSION,
+        "surface_kind": "local_macos_visibility_contract",
+        "readiness": {
+            "status": readiness_status,
+            "reason": readiness_reason,
+        },
+        "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": [
+            _mac_card(
+                "source_freshness",
+                "Source freshness",
+                "available",
+                ["source_kind", "source_freshness.status", "source_freshness.generated_at"],
+            ),
+            _mac_card(
+                "scan_integrity",
+                "Scan integrity",
+                scan_status,
+                [
+                    "scan_integrity.status",
+                    "scan_integrity.files_scanned",
+                    "scan_integrity.records_scanned",
+                    "scan_integrity.skipped_files",
+                    "scan_integrity.skipped_records",
+                ],
+            ),
+            _mac_card(
+                "token_totals",
+                "Token totals",
+                token_status,
+                [
+                    "totals.total_tokens",
+                    "totals.tokens.input",
+                    "totals.tokens.output",
+                    "totals.tokens.cache_read",
+                    "totals.tokens.cache_creation",
+                ],
+            ),
+            _mac_card(
+                "cache_reuse",
+                "Cache-read share and reuse ratio",
+                cache_status,
+                ["totals.cache_read_share", "totals.cache_reuse_ratio", "metric_availability.cache"],
+            ),
+            _mac_card(
+                "observed_cost",
+                "Observed transcript cost",
+                cost_status,
+                ["totals.cost_usd_observed", "metric_availability.cost"],
+            ),
+            _mac_card(
+                "context_availability",
+                "Context availability",
+                context_status,
+                ["context_availability", "metric_availability.context"],
+                required_observation="live_statusline_snapshot" if context_status == "missing" else None,
+            ),
+            _mac_card(
+                "headroom_availability",
+                "Headroom availability",
+                headroom_status,
+                ["headroom_availability", "cache_diagnostics.headroom_diagnostics"],
+                required_observation="live_statusline_snapshot" if headroom_status == "missing" else None,
+            ),
+            _mac_card(
+                "cache_layout_advice",
+                "Cache layout advice",
+                advice_status,
+                ["cache_layout_advice", "cache_friendliness", "cache_diagnostics.dynamic_prefix_breakers"],
+            ),
+        ],
+        "missing_live_observations": missing_live_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,
+    }
+
+
 def feasibility_json(
     summary: UsageSummary,
     top: int = 15,
@@ -1652,6 +1815,11 @@ def feasibility_json(
     cache_friendliness = cache_friendliness_for_summary(summary)
     cache_diagnostics = cache_diagnostics_for_summary(summary)
     cache_layout_advice = cache_layout_advice_for_summary(summary)
+    mac_visibility = build_mac_visibility_contract(
+        availability=availability,
+        integrity=integrity,
+        cache_layout_advice=cache_layout_advice,
+    )
     return {
         "schema_version": FEASIBILITY_SCHEMA_VERSION,
         "producer": FEASIBILITY_PRODUCER,
@@ -1672,6 +1840,7 @@ def feasibility_json(
                 "cache_friendliness",
                 "cache_diagnostics",
                 "cache_layout_advice",
+                "mac_visibility",
                 "totals",
             ],
             "diagnostic_fields": ["summary"],
@@ -1701,6 +1870,7 @@ def feasibility_json(
         "cache_friendliness": cache_friendliness,
         "cache_diagnostics": cache_diagnostics,
         "cache_layout_advice": cache_layout_advice,
+        "mac_visibility": mac_visibility,
         "totals": {
             "total_tokens": stable_total_tokens,
             "tokens": stable_tokens,