@ictechgy/context-guard 0.4.6 → 0.4.8

package/docs/benchmark-workflow-examples.md

@@ -39,6 +39,6 @@ Avoid language like:
 
 The `.example.json` fixtures intentionally use full `context-guard-bench-report-v1` shapes so tests can catch schema drift and overclaim wording.
 
-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.
+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. Use `context-guard experiments plan self-hosted-metrics-ledger --json ...` only as a dry-run ledger-preview checker for explicit metrics; it does not write the benchmark ledger.
 
 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/experimental-benchmark-fixtures.md

@@ -32,7 +32,7 @@ The visual/OCR fixtures describe sanitized textual visual evidence only and now
 
 ## Learned-compression fixture notes
 
-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.
+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. ContextGuard ships `context-guard experiments plan learned-compression` only as a deny-by-default dry-run checker for sanitized trusted prose plus exact fallback handles. It does not invoke or ship LLMLingua-style, gist-token, latent-context, embedding, reranking, model-call, or replacement-generation 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
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ictechgy/context-guard",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "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",
@@ -16,6 +16,7 @@
     "context-guard": "plugins/context-guard/bin/context-guard",
     "context-guard-setup": "plugins/context-guard/bin/context-guard-setup",
     "context-guard-diet": "plugins/context-guard/bin/context-guard-diet",
+    "context-guard-experiments": "plugins/context-guard/bin/context-guard-experiments",
     "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",

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.6.tar.gz"
+  url "https://github.com/ictechgy/context-guard/archive/refs/tags/v0.4.8.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.6"
+  "version": "0.4.8"
 }

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

@@ -113,7 +113,7 @@ 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, multimodal, 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)에 둡니다. 이 radar와 fixture는 현재 제공되는 runtime 기능이 아니며, provider가 측정한 matched-task 근거 없이 hosted API 절감을 주장하지 않습니다. Radar의 later-roadmap gate는 neural/semantic compression, trust-tiered injection-aware compression, context-diff compaction, local proxy 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만 shipped 상태이고, self-hosted metrics ledger는 `context-guard experiments plan self-hosted-metrics-ledger` dry-run preview만, local proxy는 `context-guard experiments plan local-proxy` localhost-only dry-run advisory plan만 shipped 상태이며 no listener/no traffic forwarding/no API-key persistence/read-only ledger boundary를 유지합니다. learned/synthetic compressor runtime·embedding·reranker·model call·replacement 생성, self-hosted KV/latent runtime 최적화, 실제 proxy forwarding runtime은 shipped가 아닙니다. multimodal OCR/crop은 `context-guard experiments plan visual-crop-ocr` dry-run planner만 shipped 상태이고 실제 OCR/crop runtime·스크린샷 캡처·이미지 파싱·외부 OCR/이미지 서비스 호출은 shipped가 아닙니다. 이 radar와 fixture는 provider가 측정한 matched-task 근거 없이 hosted API 절감을 주장하지 않습니다. Radar의 later-roadmap gate는 neural/semantic compression, trust-tiered injection-aware compression, context-diff compaction, local proxy constraint도 별도 미래 PR이 gate를 통과하기 전까지 experimental/non-shipped로 묶습니다.
 
 교차 에이전트 규칙 스니펫은 권고 사항입니다. 대상 에이전트가 반드시 따른다고 보장할 수 없으므로, 절감 주장이 필요하면 실제 전후 동작을 직접 측정하세요.
 

package/plugins/context-guard/README.md

@@ -119,7 +119,25 @@ 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 only 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). That radar and the fixtures are not shipped runtime features and 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, context-diff compaction, and local proxy 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 learned compression, self-hosted metrics ledger previews, and local-proxy advisory plans only; learned/synthetic compressor runtime, embeddings, rerankers, model calls, replacement generation, self-hosted KV/latent runtime optimization, and actual proxy forwarding runtime 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, context-diff compaction, and local proxy constraints experimental/non-shipped until a separate future PR satisfies those gates.
+
+## Experimental opt-ins
+
+Experimental lanes are default off. The registry is project-local metadata only; enabling an experiment records intent in `.context-guard/experiments.json` and does not activate stable runtime behavior by itself.
+
+```bash
+context-guard experiments list
+context-guard experiments status --json
+context-guard experiments plan context-diff-compaction --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 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 plan self-hosted-metrics-ledger --json --latency-ms 123.5 --peak-memory-mb 2048 --quality-score 0.98
+context-guard experiments plan local-proxy --json --bind-host 127.0.0.1 --target-host 127.0.0.1 --runtime-gate-ack
+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`, and it can 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`, and `context-guard experiments plan local-proxy`. The visual planner is shipped only as a metadata/fixture review surface: OCR/crop runtime, screenshot capture, image parsing, and external OCR/image services are not shipped. The learned-compression checker is likewise a deny-by-default dry-run policy check: learned/synthetic compressor runtime, embeddings, rerankers, model calls, and replacement generation are not shipped. The self-hosted metrics planner emits a read-only ledger-compatible preview for explicit local/model-server latency, memory, quality, energy, throughput, and local-cost metrics; it does not write a ledger or permit hosted API token/cost savings claims. The local-proxy planner emits localhost-only advisory metadata only: it starts no listener, forwards no traffic, persists no API keys, writes no ledger, blocks non-local targets, and requires a separate future runtime gate before any forwarding implementation. `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.
 

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

@@ -11,17 +11,24 @@ import json
 import os
 from pathlib import Path
 import subprocess
+import stat
 import sys
 from typing import NoReturn
 
 COMMAND_NAME = "context-guard"
 PACKAGE_NAME = "@ictechgy/context-guard"
+MAX_VERSION_METADATA_BYTES = 64 * 1024
+ALLOWED_FIRST_ABSOLUTE_SYMLINKS = {
+    "tmp": Path("/private/tmp"),
+    "var": Path("/private/var"),
+}
 
 HELPER_SUBCOMMANDS: dict[str, tuple[str, ...]] = {
     "setup": ("context-guard-setup",),
     "doctor": ("context-guard-setup", "--verify"),
     "audit": ("context-guard-audit",),
     "diet": ("context-guard-diet",),
+    "experiments": ("context-guard-experiments",),
     "scan": ("context-guard-diet", "scan"),
     "trim-output": ("context-guard-trim-output",),
     "trim": ("context-guard-trim-output",),
@@ -49,16 +56,182 @@ def _script_dir() -> Path:
 
 def _candidate_roots() -> list[Path]:
     script_dir = _script_dir()
-    roots = [script_dir.parent, script_dir.parent.parent, Path.cwd()]
+    roots = [script_dir.parent, script_dir.parent.parent]
     # When run from context-guard-kit in a checkout, the repo root is one level up.
     if script_dir.name == "context-guard-kit":
         roots.insert(0, script_dir.parent)
     return list(dict.fromkeys(roots))
 
 
+def _normalized_link_target(anchor: Path, raw_target: str) -> Path:
+    target = Path(raw_target)
+    if target.is_absolute():
+        return Path(os.path.normpath(str(target)))
+    return Path(os.path.normpath(str(anchor / target)))
+
+
+def _normalize_allowed_first_absolute_symlink(path: Path) -> Path:
+    if not path.is_absolute():
+        return path
+    parts = path.parts
+    if len(parts) < 2:
+        return path
+    expected = ALLOWED_FIRST_ABSOLUTE_SYMLINKS.get(parts[1])
+    if expected is None:
+        return path
+    first = Path(path.anchor) / parts[1]
+    try:
+        if first.is_symlink() and _normalized_link_target(Path(path.anchor), os.readlink(first)) == expected:
+            return expected.joinpath(*parts[2:])
+    except OSError:
+        return path
+    return path
+
+
+def _metadata_no_follow_supported() -> bool:
+    return (
+        hasattr(os, "O_NOFOLLOW")
+        and os.open in getattr(os, "supports_dir_fd", set())
+        and os.stat in getattr(os, "supports_dir_fd", set())
+        and os.stat in getattr(os, "supports_follow_symlinks", set())
+    )
+
+
+def _directory_open_flags(*, follow_final: bool = False) -> int:
+    flags = os.O_RDONLY
+    if hasattr(os, "O_CLOEXEC"):
+        flags |= os.O_CLOEXEC
+    if hasattr(os, "O_DIRECTORY"):
+        flags |= os.O_DIRECTORY
+    if not follow_final:
+        flags |= os.O_NOFOLLOW
+    return flags
+
+
+def _metadata_file_open_flags() -> int:
+    flags = os.O_RDONLY | os.O_NOFOLLOW
+    if hasattr(os, "O_CLOEXEC"):
+        flags |= os.O_CLOEXEC
+    if hasattr(os, "O_NONBLOCK"):
+        flags |= os.O_NONBLOCK
+    if hasattr(os, "O_NOCTTY"):
+        flags |= os.O_NOCTTY
+    return flags
+
+
+def _leaf_name(path: Path) -> str | None:
+    name = path.name
+    if name in {"", ".", ".."}:
+        return None
+    return name
+
+
+def _open_metadata_parent_no_follow(path: Path) -> int | None:
+    if not _metadata_no_follow_supported():
+        return None
+    path = _normalize_allowed_first_absolute_symlink(path)
+    try:
+        if path.is_absolute():
+            current_fd = os.open(path.anchor or os.sep, _directory_open_flags(follow_final=True))
+            parts = path.parts[1:-1]
+        else:
+            current_fd = os.open(".", _directory_open_flags(follow_final=True))
+            parts = path.parts[:-1]
+    except OSError:
+        return None
+    try:
+        for part in parts:
+            if part in {"", "."}:
+                continue
+            if part == "..":
+                return None
+            next_fd = -1
+            try:
+                next_fd = os.open(part, _directory_open_flags(), dir_fd=current_fd)
+                if not stat.S_ISDIR(os.fstat(next_fd).st_mode):
+                    try:
+                        os.close(next_fd)
+                    except OSError:
+                        pass
+                    next_fd = -1
+                    return None
+            except OSError:
+                if next_fd >= 0:
+                    try:
+                        os.close(next_fd)
+                    except OSError:
+                        pass
+                try:
+                    os.close(current_fd)
+                except OSError:
+                    pass
+                current_fd = -1
+                return None
+            try:
+                os.close(current_fd)
+            except OSError:
+                pass
+            current_fd = next_fd
+        owned_fd = current_fd
+        current_fd = -1
+        return owned_fd
+    finally:
+        if current_fd >= 0:
+            try:
+                os.close(current_fd)
+            except OSError:
+                pass
+
+
+def _read_metadata_text(path: Path) -> str | None:
+    path = _normalize_allowed_first_absolute_symlink(path)
+    parent_fd = _open_metadata_parent_no_follow(path)
+    if parent_fd is None:
+        return None
+    fd = -1
+    data = b""
+    try:
+        leaf = _leaf_name(path)
+        if leaf is None:
+            return None
+        pre_open = os.stat(leaf, dir_fd=parent_fd, follow_symlinks=False)
+        if not stat.S_ISREG(pre_open.st_mode):
+            return None
+        if pre_open.st_size > MAX_VERSION_METADATA_BYTES:
+            return None
+        fd = os.open(leaf, _metadata_file_open_flags(), dir_fd=parent_fd)
+        opened = os.fstat(fd)
+        if not stat.S_ISREG(opened.st_mode):
+            return None
+        if opened.st_size > MAX_VERSION_METADATA_BYTES:
+            return None
+        data = os.read(fd, MAX_VERSION_METADATA_BYTES + 1)
+    except OSError:
+        return None
+    finally:
+        if fd >= 0:
+            try:
+                os.close(fd)
+            except OSError:
+                pass
+        try:
+            os.close(parent_fd)
+        except OSError:
+            pass
+    if len(data) > MAX_VERSION_METADATA_BYTES:
+        return None
+    try:
+        return data.decode("utf-8")
+    except UnicodeDecodeError:
+        return None
+
+
 def _load_json(path: Path) -> dict[str, object] | None:
+    text = _read_metadata_text(path)
+    if text is None:
+        return None
     try:
-        data = json.loads(path.read_text(encoding="utf-8"))
+        data = json.loads(text)
     except (OSError, json.JSONDecodeError):
         return None
     return data if isinstance(data, dict) else None

package/plugins/context-guard/bin/context-guard-artifact

@@ -766,10 +766,20 @@ def cap_text(text: str, max_chars: int) -> tuple[str, bool]:
     return text[:keep].rstrip() + marker, True
 
 
-def query_content(content: str, *, line_range: tuple[int, int] | None, pattern: str | None, max_lines: int) -> tuple[str, dict[str, object]]:
+def query_content(
+    content: str,
+    *,
+    line_range: tuple[int, int] | None,
+    pattern: str | None,
+    max_lines: int,
+    full: bool = False,
+) -> tuple[str, dict[str, object]]:
     lines = content.splitlines(True)
     selected: list[tuple[int, str]] = []
-    if line_range is not None:
+    if full:
+        selected = list(enumerate(lines, start=1))
+        selector = {"type": "full"}
+    elif line_range is not None:
         start, end = line_range
         selected = list(enumerate(lines[start - 1 : end], start=start))
         selector = {"type": "lines", "start": start, "end": end}
@@ -780,15 +790,18 @@ def query_content(content: str, *, line_range: tuple[int, int] | None, pattern:
         selected = list(enumerate(lines[:max_lines], start=1))
         selector = {"type": "head", "max_lines": max_lines}
     total_matches = len(selected)
-    selected = selected[:max_lines]
+    if not full:
+        selected = selected[:max_lines]
     text = "".join(line for _idx, line in selected)
     return text, {"selector": selector, "returned_lines": len(selected), "matched_lines": total_matches, "total_lines": len(lines)}
 
 
 def get_command(args: argparse.Namespace) -> int:
     artifact_id = args.artifact_id
-    max_chars = bounded_int(args.max_chars, DEFAULT_MAX_CHARS, 1, 1_000_000)
+    full = bool(getattr(args, "full", False))
     try:
+        if full and (args.lines or args.pattern or args.max_lines is not None):
+            raise ValueError("--full cannot be combined with --lines, --pattern, or --max-lines")
         last_missing: FileNotFoundError | None = None
         for directory in artifact_read_directories(args.dir):
             try:
@@ -815,12 +828,14 @@ def get_command(args: argparse.Namespace) -> int:
         actual_sha = hashlib.sha256(content.encode("utf-8", errors="replace")).hexdigest()
         if actual_sha != expected_sha:
             raise ValueError(f"artifact content checksum mismatch: {artifact_id}")
+        default_max_chars = max(DEFAULT_MAX_CHARS, expected_bytes) if full else DEFAULT_MAX_CHARS
+        max_chars = bounded_int(args.max_chars, default_max_chars, 1, MAX_MAX_BYTES)
         line_range = parse_line_range(args.lines)
         if line_range is not None and args.max_lines is None:
             max_lines = min(line_range[1] - line_range[0] + 1, MAX_QUERY_LINES)
         else:
             max_lines = bounded_int(args.max_lines, DEFAULT_MAX_LINES, 1, MAX_QUERY_LINES)
-        selected, query = query_content(content, line_range=line_range, pattern=args.pattern, max_lines=max_lines)
+        selected, query = query_content(content, line_range=line_range, pattern=args.pattern, max_lines=max_lines, full=full)
         selected, capped = cap_text(selected, max_chars)
     except (FileNotFoundError, ValueError, OSError, json.JSONDecodeError) as exc:
         print(f"context-guard-artifact: {exc}", file=sys.stderr)
@@ -895,7 +910,8 @@ def build_parser() -> argparse.ArgumentParser:
     get.add_argument("--lines", help="1-based inclusive line range, e.g. 10:40")
     get.add_argument("--pattern", help="literal substring filter")
     get.add_argument("--max-lines", type=int, default=None)
-    get.add_argument("--max-chars", type=int, default=DEFAULT_MAX_CHARS)
+    get.add_argument("--full", action="store_true", help="return full stored artifact content; cannot be combined with selectors")
+    get.add_argument("--max-chars", type=int, default=None)
     get.add_argument("--json", action="store_true", help="emit query JSON with content")
     get.set_defaults(func=get_command)