@ictechgy/context-guard 0.4.16 → 0.6.0

package/plugins/context-guard/README.md

@@ -46,6 +46,15 @@ context-guard setup --agent codex --scope project --brief-mode standard --plan
 npx @ictechgy/context-guard --version
 ```
 
+The compact `bash_reference_v1` Bash-output route is intentionally not
+available from this marketplace-plugin/source layout. It requires an exact
+project-local npm installation of `@ictechgy/context-guard@0.5.0` and its
+`@ictechgy/context-guard-receipt@0.2.0` dependency, then explicit
+`setup --agent claude --scope project --bash-reference-v1`. Plugin setup keeps
+legacy trimming and warns instead of installing a no-op reference flag. See the
+repository distribution guide for activation, disablement, seven-day handle,
+and preserved-state details.
+
 From this repository root, run helpers by path:
 
 ```bash
@@ -71,6 +80,8 @@ context-guard-artifact store --command "long-command" --json < large.log
 context-guard-artifact search "ERROR" --json
 context-guard-artifact receipt <artifact_id> --json
 context-guard-artifact get <artifact_id> --lines 1:80
+context-guard task-memory put --task issue-123 --source src/app.py --json < stable-context.txt
+context-guard task-memory get <opaque_handle> --task issue-123 --source src/app.py --max-bytes 65536
 context-guard-compress --json < large-output.txt
 context-guard-compress --json --protected-policy < evidence.txt
 context-guard-compress --json --type prose --mode readable < sanitized-prose.txt
@@ -84,6 +95,8 @@ context-guard-sanitize-output -- git diff
 context-guard-filter validate --config .context-guard/filter-dsl.json
 context-guard-filter run --config .context-guard/filter-dsl.json -- git status --short
 context-guard-pack auto --root . --query "review failing tests" --diff HEAD --manifest-out suggested-pack.json --pack-out context-pack.md --budget-bytes 12000 --json --explain --adaptive-k --adaptive-k-policy recall --symbol-memory
+context-guard-pack auto --root . --files src/app.py --query "review entrypoint" --top 1 --budget-bytes 12000 --json --no-artifact --apply-symbol-memory
+context-guard-pack auto --root . --query "review failing tests" --top 8 --budget-bytes 12000 --json --no-artifact --apply-adaptive-k
 context-guard-pack build --root . --manifest suggested-pack.json --budget-bytes 12000 --json
 context-guard-pack build --root . --manifest suggested-pack.json --budget-bytes 12000 --json --no-artifact --delta-from-pack-id 0123456789abcdef0123
 context-guard-pack slice --root . --path README.md --lines 1:40 --json
@@ -108,8 +121,17 @@ Opt-in `build`/`auto --sketch-duplicate-veto` applies a rank-stable pre-budget g
 - **Large-read guard and symbol reader** guide the agent from search to symbol slices to small line ranges before attempting a whole-file read. Supported source slices include Python, JavaScript/TypeScript, Go, and Rust.
 - **Declarative output filter** validates user-owned JSON filter files outside package code and applies the first matching line filter only as an explicit `run --config ... -- <command>` wrapper. Invalid configs, no-match commands, filter errors, empty filtered output, and protected `git`/test/lint/`gh` command failures preserve original stdout/stderr and exit code. Filtered mode applies line rules to combined stdout+stderr and writes the filtered result to stdout; `--json-report` diagnostics go to stderr, except protected nonzero passthrough suppresses reports to keep stderr raw. It is local and opt-in, with no savings guarantee.
 - **Artifact store** saves large sanitized command output under `.context-guard/artifacts` by default and returns compact receipts, local sandbox search results, or exact requested slices. JSON receipts include line-numbered top errors, duplicate-line groups, sanitized bounded suggested queries, and an `output_sandbox` envelope with a stable `contextguard-artifact:<id>` handle. `receipt <artifact_id> --json` rehydrates metadata-only handles without content. `search` scans sanitized local artifacts by literal substring, emits capped match/context records, and includes `get --lines START:END` rehydration commands without hosted token/cost savings claims. Custom `--dir` raw paths stay redacted by default; reuse the same `--dir` or opt into `search --show-paths` for a directly executable local command. In suggested `--lines START:END` queries, `--max-lines` is only the returned-line cap for that selected range, not a wider selector. `get`, `list`, and `search` can also read legacy `.claude-token-optimizer/artifacts` receipts.
-- **Budgeted context packer** assembles prioritized local file evidence into a rendered byte-budgeted Markdown pack with included/partial/omitted source metadata, bounded `.context-guard/packs` receipts, exact sanitized `slice` commands when safe, and `retrieval_omitted_reason` when a path/root should not be echoed. The additive `auto` subcommand runs that recommendation and pack build in one step, and `auto --explain` adds compact deterministic local selection/build reasons without changing the manifest, pack body, receipt, or byte budget. JSON explain also includes bounded repo-map metadata: sampled byte/token-proxy tree entries, category-only secret-risk counts, signature-first hints, explain-only graph ranks, and exact `slice`/symbol retrieval hints. `suggest` remains available to rank local query, diff, explicit file, and sanitized output/test-output signals into a build-compatible manifest without network, model, embedding, or provider-cost calls. `suggest/auto --adaptive-k` adds advisory-only shrink/expand top-k metadata from local score distribution, byte-budget fit, and clamped score-mass recall/precision proxies. `--adaptive-k-policy balanced|recall|precision` plus optional recall/precision proxy gates selects the local recommendation policy; gate failures are metadata-only. The adaptive block includes capped selected/omitted evidence and structured source-verification hints, and it never applies the recommendation automatically or changes the manifest, pack body, receipt, or byte budget. `auto --symbol-memory` adds repo-map-derived symbol/graph advisory metadata with exact `slice`/`read-symbol` verification hints and still does not change selection or pack output. Token counts are estimated `chars_div_4` proxies, not measured provider-token savings.
+- **Task memory** explicitly stores stable, secret-free task context in owner-private authenticated project storage. Opaque `contextguard-memory:` handles disclose neither paths nor content. Every bounded `get` revalidates the physical project, Git revision/worktree, task, source digests, expiry, modes, links, quotas, content digest, and authentication before writing content to stdout. It is provider-free and makes no token/cost savings guarantee.
+- **Budgeted context packer** assembles prioritized local file evidence into a rendered byte-budgeted Markdown pack with included/partial/omitted source metadata, bounded `.context-guard/packs` receipts, exact sanitized `slice` commands when safe, and `retrieval_omitted_reason` when a path/root should not be echoed. The additive `auto` subcommand runs that recommendation and pack build in one step, and `auto --explain` adds compact deterministic local selection/build reasons without changing the manifest, pack body, receipt, or byte budget. JSON explain also includes bounded repo-map metadata: sampled byte/token-proxy tree entries, category-only secret-risk counts, signature-first hints, explain-only graph ranks, and exact `slice`/symbol retrieval hints. `suggest` remains available to rank local query, diff, explicit file, and sanitized output/test-output signals into a build-compatible manifest without network, model, embedding, or provider-cost calls. `suggest/auto --adaptive-k` adds advisory-only shrink/expand top-k metadata from local score distribution, byte-budget fit, and clamped score-mass recall/precision proxies. `--adaptive-k-policy balanced|recall|precision` plus optional recall/precision proxy gates selects the local recommendation policy; gate failures are metadata-only. The adaptive block includes capped selected/omitted evidence and structured source-verification hints, and it never applies the recommendation automatically or changes the manifest, pack body, receipt, or byte budget. `auto --symbol-memory` adds repo-map-derived symbol/graph advisory metadata with exact `slice`/`read-symbol` verification hints and still does not change selection or pack output. Explicit `auto --apply-symbol-memory` instead adds at most four safe direct import-neighbor slices, keeps explicit/query seeds at higher priority, excludes secret-risk neighbors, and rebuilds within the same byte budget while retaining exact fallback and a closed `graph_application` record. Token counts are estimated `chars_div_4` proxies, not measured provider-token savings.
+- `auto --self-financing-selection` is the default-off composed path: Adaptive first, then task-matching Symbol slices, then bounded one-hop Graph neighbors under the frozen ordinary-pack byte ceiling. It never displaces caller/critical sources and records frozen identity, secret decision, byte delta, exact fallback, replacement removals, or an honest no-op for every candidate. It makes no provider savings claim.
+- `auto --selection-plan --json` emits only a provider-free, read-only closed plan from the query, diff, output/log, symbol, and self-financing inputs. Save it explicitly and pass the same inputs with `--apply-selection-plan PATH` to apply it. Apply recomputes the plan and revalidates source identities before output; incomplete scans, secret-risk or scorer/private inputs, drift, unsafe output boundaries, and missing exact recovery fail closed.
+
+```bash
+context-guard-pack auto --root . --query "fix retry" --diff worktree --output logs/test.txt --json --selection-plan > selection-plan.json
+context-guard-pack auto --root . --query "fix retry" --diff worktree --output logs/test.txt --json --apply-selection-plan selection-plan.json --no-artifact
+```
 - **Tool/MCP schema pruner** ranks local tool catalogs into bounded top-k advisory reports while preserving full sanitized schema fallback through compact receipts and payload integrity checks. `defer-report` additionally separates core inline tools from deferred stubs/namespaces and reports gross deferred-schema plus net initial-report char/4 proxy accounting; full schemas still must be retrieved before deferred tool use.
+- **Applied adaptive breadth** is available only through explicit `auto --apply-adaptive-k`. It prunes heuristic-selected sources after local regression gates pass, always retains caller-declared file/output/test-output and diff sources, rebuilds within the same byte budget, and records `adaptive_k_application`; local proxies do not authorize provider-token or cost-savings claims.
 - **Conservative compressor** classifies sanitized stdin as JSON, diff, log, search output, code, or prose and shrinks it with observed byte evidence plus estimated token proxies. Add `--protected-policy` for opt-in protected-zone class/count metadata that denies semantic rewrites for code fences, diffs, identifiers, numeric constants, hashes, paths, stack frames, quoted strings, and JSON keys while preserving exact-retrieval guidance. Add `--mode readable` only for sanitized prose previews: it uses deterministic sentence windows, blocks prompt-like/high-risk protected signals, stores no raw protected spans, and does not run learned compressors, models, embeddings, or rerankers.
 - **Static cache-score lint plus Anthropic cost guard and route advisor** provides `context-guard-cache-score` for local prompt/request cache layout checks, with optional user-supplied cache write/read multiplier amortization risk, and `context-guard cost preflight/observe/ledger/compile` for passive pre-call estimates, provider-usage reconciliation, keyed-HMAC cache-risk history, and stable-prefix layout advice. `context-guard route-advisor` is a local-only passive advisor for caller-supplied workload JSON, provider feature declarations, usage telemetry, and shifted external/local costs; it emits total-cost accounting, batchability blockers, and route candidates without starting a queue, calling providers, refreshing pricing docs, or treating provider feature knowledge as authoritative. It stores no raw prompt text, does not replace Anthropic/provider prompt caching, and its recommendations are not hosted token/cost savings claims without matched successful tasks, non-inferior quality evidence, and shifted-cost accounting.
 - **Output trimmer** preserves the wrapped command exit code, trims long logs, and can emit `--digest markdown` or `--digest json` summaries with runner failure facts, sanitized failure signatures, duplicate-line groups, and suggested next queries. Add `--artifact-receipt` with digest mode to store the exact sanitized full output as a local artifact receipt; keep the `contextguard-artifact:<id>` handle and re-expand omitted slices with emitted `context-guard-artifact receipt/get/search ...` commands.
@@ -196,6 +218,19 @@ Cross-agent rule snippets are advisory: the target agent may ignore them, so mea
 
 `context-guard mcp` and `context-guard-mcp` launch a dependency-free local stdio MCP child process. A process is isolated to one root and namespace and exposes only sanitized compression, sanitized exact artifact fallback, and local statistics. It has no HTTP, network, provider, model, or proxy integration and never mutates client configuration. Artifacts are inaccessible across namespaces; no hosted token/cost savings are claimed.
 
+The installed Receipt companion can also be launched explicitly as
+`context-guard-receipt-mcp --root /absolute/repository`. Its
+`receipt_context` tool stores one explicitly eligible relative file or log as a
+compact process-local exact reference when the conservative byte router finds
+that beneficial, reuses the live reference, and reads exact slices of at most
+65,536 bytes. Optional task scopes and explicit release provide process-local
+context GC; content-free history stores only keyed digests and decisions.
+`receipt_diagnose` exposes non-applying firewall/router and prefix-reuse
+scout/surgeon advice, while an explicit private `--state-dir` enables only the
+authenticated advisory `receipt_twin`. It does not auto-register, intercept
+prompts, persist capabilities across restart, call a provider, or make a hosted
+savings claim.
+
 ## Local test before publishing
 
 From the marketplace repository root: