@ictechgy/context-guard 0.4.0 → 0.4.3

package/docs/cache-diagnostics.example.json

@@ -0,0 +1,116 @@
+{
+  "cache_miss_hypotheses": [
+    {
+      "action": "Move diffs, logs, timestamps, and command output after stable reusable prompt prefixes.",
+      "confidence": "partial",
+      "evidence": "inferred",
+      "id": "volatile-prefix-breakers",
+      "reason": "Redacted prompt segment hashes show volatile content near the prefix window."
+    }
+  ],
+  "caveats": [
+    "Cache diagnostics are local transcript heuristics and do not prove exact provider cache-prefix state.",
+    "Provider cache read/write fields are diagnostic telemetry and do not prove ContextGuard-caused token reduction.",
+    "Stable-prefix and breaker positions come from bounded redacted segment hashes, not raw prompt text."
+  ],
+  "confidence": "hypothesis",
+  "derived_ratios": {
+    "cache_read_share": {
+      "evidence": "inferred",
+      "value": 0.7009345794392523
+    },
+    "cache_reuse_ratio": {
+      "evidence": "inferred",
+      "value": 2.5
+    }
+  },
+  "dynamic_prefix_breakers": [
+    {
+      "action": "Move diffs, logs, timestamps, and command output after stable reusable prompt prefixes.",
+      "confidence": "partial",
+      "evidence": "inferred",
+      "heuristic": true,
+      "position": 2,
+      "sample_count": 2,
+      "stability": 0.5,
+      "trigger": "prefix_position",
+      "unique_hashes": 2,
+      "volatile_share": 0.5
+    }
+  ],
+  "evidence": "inferred",
+  "headroom_diagnostics": {
+    "evidence": "unavailable",
+    "historical_total_tokens_are_not_headroom": true,
+    "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.",
+    "required_observation": "live_statusline_snapshot",
+    "status": "missing"
+  },
+  "heuristic": true,
+  "observations": {
+    "cache_creation_tokens": 60000,
+    "cache_fields": {
+      "derived": {
+        "cache_read_share": {
+          "evidence": "inferred",
+          "value": 0.7009345794392523
+        },
+        "cache_reuse_ratio": {
+          "evidence": "inferred",
+          "value": 2.5
+        }
+      },
+      "evidence": "observed",
+      "present_fields": {
+        "cache_creation": 2,
+        "cache_read": 2
+      },
+      "status": "available",
+      "zero_values_observed": {
+        "cache_creation": false,
+        "cache_read": false
+      }
+    },
+    "cache_read_tokens": 150000
+  },
+  "schema_version": "contextguard.cache-diagnostics.v1",
+  "stable_prefix_candidates": [
+    {
+      "action": "Keep stable instructions, policies, and reusable context before run-specific evidence.",
+      "confidence": "partial",
+      "evidence": "inferred",
+      "position": 0,
+      "sample_count": 2,
+      "stability": 1.0,
+      "unique_hashes": 1,
+      "volatile_share": 0.0
+    },
+    {
+      "action": "Keep stable instructions, policies, and reusable context before run-specific evidence.",
+      "confidence": "partial",
+      "evidence": "inferred",
+      "position": 1,
+      "sample_count": 2,
+      "stability": 1.0,
+      "unique_hashes": 1,
+      "volatile_share": 0.0
+    }
+  ],
+  "status": "partial",
+  "ttl_diagnostics": {
+    "candidate": "between-5m-and-1h",
+    "caveats": [
+      "Timestamped cache telemetry records do not prove exact provider cache-prefix identity or provider cache TTL state.",
+      "5-minute versus 1-hour TTL guidance is a local hypothesis unless corroborated with provider telemetry and repeated stable prefixes."
+    ],
+    "confidence": "hypothesis",
+    "evidence": "inferred",
+    "interval_basis": "positive_timestamped_cache_records",
+    "positive_timestamped_cache_record_count": 2,
+    "reason": "Positive timestamped cache telemetry records bound the local cache-observation span, but exact provider cache TTL reuse remains a hypothesis.",
+    "status": "hypothesis",
+    "timestamped_cache_record_count": 2,
+    "timestamped_cache_record_span_seconds": 450
+  }
+}

package/docs/cache-diagnostics.schema.json

@@ -0,0 +1,460 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/ictechgy/context-guard/docs/cache-diagnostics.schema.json",
+  "title": "ContextGuard cache_diagnostics object",
+  "description": "Schema reference for the nested cache_diagnostics object emitted by context-guard-audit --json and --feasibility-json. It is not the full CLI response envelope.",
+  "type": "object",
+  "additionalProperties": true,
+  "required": [
+    "schema_version",
+    "status",
+    "confidence",
+    "evidence",
+    "heuristic",
+    "observations",
+    "derived_ratios",
+    "stable_prefix_candidates",
+    "dynamic_prefix_breakers",
+    "cache_miss_hypotheses",
+    "ttl_diagnostics",
+    "headroom_diagnostics",
+    "caveats"
+  ],
+  "properties": {
+    "schema_version": {
+      "const": "contextguard.cache-diagnostics.v1"
+    },
+    "status": {
+      "enum": [
+        "available",
+        "partial",
+        "missing"
+      ]
+    },
+    "confidence": {
+      "enum": [
+        "observed",
+        "partial",
+        "hypothesis",
+        "unavailable"
+      ]
+    },
+    "evidence": {
+      "enum": [
+        "observed",
+        "inferred",
+        "unavailable"
+      ]
+    },
+    "heuristic": {
+      "type": "boolean",
+      "const": true
+    },
+    "observations": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": [
+        "cache_fields",
+        "cache_read_tokens",
+        "cache_creation_tokens"
+      ],
+      "properties": {
+        "cache_read_tokens": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "cache_creation_tokens": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "cache_fields": {
+          "type": "object",
+          "additionalProperties": true,
+          "required": [
+            "status",
+            "evidence",
+            "present_fields",
+            "zero_values_observed",
+            "derived"
+          ],
+          "properties": {
+            "status": {
+              "enum": [
+                "available",
+                "partial",
+                "missing"
+              ]
+            },
+            "evidence": {
+              "enum": [
+                "observed",
+                "inferred",
+                "unavailable"
+              ]
+            },
+            "present_fields": {
+              "type": "object",
+              "required": [
+                "cache_read",
+                "cache_creation"
+              ],
+              "properties": {
+                "cache_read": {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                "cache_creation": {
+                  "type": "integer",
+                  "minimum": 0
+                }
+              },
+              "additionalProperties": true
+            },
+            "zero_values_observed": {
+              "type": "object",
+              "required": [
+                "cache_read",
+                "cache_creation"
+              ],
+              "properties": {
+                "cache_read": {
+                  "type": "boolean"
+                },
+                "cache_creation": {
+                  "type": "boolean"
+                }
+              },
+              "additionalProperties": true
+            },
+            "derived": {
+              "$ref": "#/$defs/derivedRatios"
+            }
+          }
+        }
+      }
+    },
+    "derived_ratios": {
+      "$ref": "#/$defs/derivedRatios"
+    },
+    "stable_prefix_candidates": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/prefixCandidate"
+      }
+    },
+    "dynamic_prefix_breakers": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/prefixBreaker"
+      }
+    },
+    "cache_miss_hypotheses": {
+      "type": "array",
+      "items": {
+        "$ref": "#/$defs/hypothesis"
+      }
+    },
+    "ttl_diagnostics": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": [
+        "status",
+        "evidence",
+        "confidence",
+        "timestamped_cache_record_count",
+        "positive_timestamped_cache_record_count",
+        "timestamped_cache_record_span_seconds",
+        "candidate",
+        "reason",
+        "interval_basis",
+        "caveats"
+      ],
+      "properties": {
+        "status": {
+          "enum": [
+            "hypothesis",
+            "unavailable"
+          ]
+        },
+        "evidence": {
+          "enum": [
+            "inferred",
+            "unavailable"
+          ]
+        },
+        "confidence": {
+          "enum": [
+            "partial",
+            "hypothesis",
+            "unavailable"
+          ]
+        },
+        "timestamped_cache_record_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "positive_timestamped_cache_record_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "timestamped_cache_record_span_seconds": {
+          "type": [
+            "integer",
+            "null"
+          ],
+          "minimum": 0
+        },
+        "candidate": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "enum": [
+            "within-5m",
+            "between-5m-and-1h",
+            "beyond-1h",
+            null
+          ]
+        },
+        "reason": {
+          "type": "string"
+        },
+        "interval_basis": {
+          "const": "positive_timestamped_cache_records"
+        },
+        "caveats": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "headroom_diagnostics": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": [
+        "status",
+        "evidence",
+        "observable_via",
+        "reason",
+        "historical_total_tokens_are_not_headroom",
+        "required_observation"
+      ],
+      "properties": {
+        "status": {
+          "enum": [
+            "missing",
+            "unavailable"
+          ]
+        },
+        "evidence": {
+          "const": "unavailable"
+        },
+        "observable_via": {
+          "const": "live_statusline_snapshot"
+        },
+        "required_observation": {
+          "const": "live_statusline_snapshot"
+        },
+        "historical_total_tokens_are_not_headroom": {
+          "type": "boolean",
+          "const": true
+        },
+        "reason": {
+          "type": "string"
+        }
+      }
+    },
+    "caveats": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    }
+  },
+  "$defs": {
+    "derivedRatios": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": [
+        "cache_read_share",
+        "cache_reuse_ratio"
+      ],
+      "properties": {
+        "cache_read_share": {
+          "$ref": "#/$defs/ratio"
+        },
+        "cache_reuse_ratio": {
+          "$ref": "#/$defs/ratio"
+        }
+      }
+    },
+    "ratio": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": [
+        "value",
+        "evidence"
+      ],
+      "properties": {
+        "value": {
+          "type": [
+            "number",
+            "null"
+          ]
+        },
+        "evidence": {
+          "enum": [
+            "inferred",
+            "unavailable"
+          ]
+        }
+      }
+    },
+    "prefixCandidate": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": [
+        "position",
+        "stability",
+        "volatile_share",
+        "unique_hashes",
+        "sample_count",
+        "evidence",
+        "confidence",
+        "action"
+      ],
+      "properties": {
+        "position": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "stability": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "volatile_share": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "unique_hashes": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "sample_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "evidence": {
+          "const": "inferred"
+        },
+        "confidence": {
+          "enum": [
+            "partial",
+            "hypothesis"
+          ]
+        },
+        "action": {
+          "type": "string"
+        }
+      }
+    },
+    "prefixBreaker": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": [
+        "position",
+        "trigger",
+        "volatile_share",
+        "stability",
+        "unique_hashes",
+        "sample_count",
+        "evidence",
+        "confidence",
+        "heuristic",
+        "action"
+      ],
+      "properties": {
+        "position": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "trigger": {
+          "type": "string"
+        },
+        "volatile_share": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "stability": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 1
+        },
+        "unique_hashes": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "sample_count": {
+          "type": "integer",
+          "minimum": 0
+        },
+        "evidence": {
+          "const": "inferred"
+        },
+        "confidence": {
+          "enum": [
+            "partial",
+            "hypothesis"
+          ]
+        },
+        "heuristic": {
+          "type": "boolean",
+          "const": true
+        },
+        "action": {
+          "type": "string"
+        }
+      }
+    },
+    "hypothesis": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": [
+        "id",
+        "evidence",
+        "confidence",
+        "reason",
+        "action"
+      ],
+      "properties": {
+        "id": {
+          "type": "string"
+        },
+        "evidence": {
+          "enum": [
+            "inferred",
+            "unavailable"
+          ]
+        },
+        "confidence": {
+          "enum": [
+            "partial",
+            "hypothesis",
+            "unavailable"
+          ]
+        },
+        "reason": {
+          "type": "string"
+        },
+        "action": {
+          "type": "string"
+        }
+      }
+    }
+  }
+}

package/docs/distribution.md

@@ -13,17 +13,19 @@ ContextGuard separates **install** from **activation**.
 | Claude Code plugin | shipped | `/plugin marketplace add ictechgy/context-guard` then `/plugin install context-guard@context-guard` | Best native Claude Code workflow. |
 | npm global | added | `npm install -g @ictechgy/context-guard` | Installs `context-guard` and helper aliases on PATH. |
 | npx/npm exec | added | `npx @ictechgy/context-guard --version` | One-off usage; activation still requires explicit setup. |
-| Homebrew | draft | `brew tap ictechgy/contextguard && brew install context-guard` | Formula template exists under `packaging/homebrew/`; publish after release artifact SHA is known. |
+| Homebrew | shipped | `brew install ictechgy/tap/context-guard` | Formula is published in `ictechgy/homebrew-tap`; update it from a tagged release tarball SHA. |
 
 ## Activation examples
 
 ```bash
+context-guard doctor --root . --json
 context-guard setup --agent codex --scope project --with-init --with-skill --plan
 context-guard setup --agent codex --scope project --with-init --with-skill --yes
+context-guard setup --agent claude --scope user --verify --json
 context-guard setup --agent claude --scope user --plan
 ```
 
-Project scope is the default. User scope is opt-in and requires an explicit agent for writes. Supported user-scope writes record backups and rollback metadata under `.context-guard/rollback` in the user home directory.
+Project scope is the default. `context-guard doctor` and `context-guard setup --verify` are read-only health checks. User scope is opt-in and requires an explicit agent for writes. Supported user-scope writes record backups and rollback metadata under `.context-guard/rollback` in the user home directory.
 
 ## Runtime requirements
 

package/docs/experimental-benchmark-fixtures.md

@@ -0,0 +1,36 @@
+# 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.
+
+Use them when designing an experiment that starts from ContextGuard's existing benchmark discipline:
+
+1. Run `context-guard-bench --tasks ... --variants ... --csv ... --dry-run` first to validate command shape. Dry-run output confirms only the argv shape; it is not benchmark evidence.
+   Unchanged fixture files are dry-run-only starters: before any non-dry-run benchmark, replace the placeholder prompts and replace the failing placeholder `success_command` with an explicit success check or documented manual correction/evaluation workflow.
+2. Replace the placeholder prompts with sanitized project tasks and run baseline plus variant on the same task set.
+3. Compare only **matched successful tasks**.
+4. Record the **failure-rate guardrail**, **human corrections**, and **shifted-cost accounting** for work moved to local tools, subagents, artifact stores, OCR tools, or compressors.
+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.
+
+## 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 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.
+
+## 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.
+
+## Safe wording
+
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ictechgy/context-guard",
-  "version": "0.4.0",
+  "version": "0.4.3",
   "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",
@@ -19,6 +19,7 @@
     "context-guard-audit": "plugins/context-guard/bin/context-guard-audit",
     "context-guard-trim-output": "plugins/context-guard/bin/context-guard-trim-output",
     "context-guard-sanitize-output": "plugins/context-guard/bin/context-guard-sanitize-output",
+    "context-guard-filter": "plugins/context-guard/bin/context-guard-filter",
     "context-guard-artifact": "plugins/context-guard/bin/context-guard-artifact",
     "context-guard-pack": "plugins/context-guard/bin/context-guard-pack",
     "context-guard-tool-prune": "plugins/context-guard/bin/context-guard-tool-prune",
@@ -29,7 +30,8 @@
     "context-guard-guard-read": "plugins/context-guard/bin/context-guard-guard-read",
     "context-guard-failed-nudge": "plugins/context-guard/bin/context-guard-failed-nudge",
     "context-guard-statusline": "plugins/context-guard/bin/context-guard-statusline",
-    "context-guard-statusline-merged": "plugins/context-guard/bin/context-guard-statusline-merged"
+    "context-guard-statusline-merged": "plugins/context-guard/bin/context-guard-statusline-merged",
+    "context-guard-cost": "plugins/context-guard/bin/context-guard-cost"
   },
   "files": [
     "CHANGELOG.md",
@@ -50,6 +52,13 @@
     "plugins/context-guard/lib/**",
     "plugins/context-guard/skills/**",
     "docs/distribution.md",
+    "docs/cache-diagnostics-schema.md",
+    "docs/cache-diagnostics.schema.json",
+    "docs/cache-diagnostics.example.json",
+    "docs/benchmark-workflows/*.example.json",
+    "docs/benchmark-workflow-examples.md",
+    "docs/benchmark-fixtures/*.example.json",
+    "docs/experimental-benchmark-fixtures.md",
     "packaging/homebrew/context-guard.rb.template"
   ],
   "engines": {

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.0.tar.gz"
+  url "https://github.com/ictechgy/context-guard/archive/refs/tags/v0.4.3.tar.gz"
   sha256 "REPLACE_WITH_RELEASE_TARBALL_SHA256"
   license "Apache-2.0"
 
@@ -17,7 +17,8 @@ class ContextGuard < Formula
     libexec.install "plugins"
 
     python_shebang = detected_python_shebang
-    Dir[libexec/"plugins/context-guard/bin/*"].each do |command|
+    Dir[libexec/"plugins/context-guard/bin/*"].each do |path|
+      command = Pathname(path)
       next unless command.file?
 
       first_line = command.open { |file| file.gets.to_s }