@ictechgy/context-guard 0.4.3 → 0.4.4

package/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 All notable changes for the ContextGuard plugin are documented here.
 
+## [0.4.4] - 2026-06-08
+
+- Added top-level `cache_layout_advice` to transcript audit JSON and feasibility output so cache-prefix instability can be prioritized without mixing advice into evidence-only diagnostics.
+- Documented the `cache_layout_advice` consumer contract and conservative cause boundaries for volatile-prefix findings.
+- Refined cache-prefix recommendation wording after quad-review so advice does not overclaim cache reads or session-splitting evidence.
+
 ## [0.4.3] - 2026-06-08
 
 - Fixed the Homebrew formula template so packaged helper paths are handled as Pathname objects during install.

package/README.ko.md

@@ -99,7 +99,7 @@ brief 모드는 코딩 에이전트가 군더더기를 줄이도록 요청하되
 
 - 전체 파일 읽기와 심볼·줄 범위 읽기의 차이
 - 원본 로그와 요약 출력 또는 로컬 보관 요약 기록의 차이
-- `context-guard-audit`가 보고한 대화 기록 사용량 집중 지점과 `cache_friendliness` 프롬프트 배치 신호
+- `context-guard-audit`가 보고한 대화 기록 사용량 집중 지점, `cache_friendliness` 프롬프트 배치 신호, `cache_layout_advice` 실험 우선순위
 - 상태표시줄의 `cache` / `reuse` 값: ContextGuard가 직접 만든 절감 효과가 아니라 관찰된 대화 기록·provider cache 신호입니다.
 - `context-guard cost preflight`로 Anthropic 요청 JSON의 추정 비용을 보고, 호출 뒤 `context-guard cost observe`로 provider usage 필드(`cache_creation_input_tokens`, `cache_read_input_tokens`)를 대조합니다.
 - `context-guard-bench`로 성공한 기준/변형 실행을 쌍으로 맞춰 비교한 결과
@@ -300,7 +300,7 @@ head/tail 로그 대신 의미 요약이 필요하면 `--digest markdown` 또는
 ./plugins/context-guard/bin/context-guard-audit ~/.claude/projects --top 20 --recommend
 ```
 
-감사 명령은 기본적으로 너무 큰 대화 기록 파일과 JSONL 기록을 건너뛰고(`--max-file-bytes`, `--max-line-bytes`), 건너뛴 개수를 함께 보고합니다. 손상된 추적 기록이 메모리를 독점하거나 스캔 공백을 숨기지 않도록 하기 위한 방어입니다. JSON 출력에는 `cache_friendliness`와 [`cache_diagnostics`](docs/cache-diagnostics-schema.md)도 포함됩니다. 이는 제한된 사용량 필드, timestamped cache telemetry records, 가림 처리된 segment hash로 만든 휴리스틱 프롬프트 배치/cache-read 진단이며, 자주 바뀌는 내용이 프롬프트 앞부분에 있는지, 안정 prefix 후보가 있는지, cache miss 가설과 TTL/headroom 증거 공백이 무엇인지 알릴 수 있습니다. 원문 프롬프트는 출력하지 않고 provider cache hit를 증명하지 않으며, 대화 기록 스키마가 충분한 증거를 드러내지 않으면 `missing`, `partial`, `hypothesis`, `unavailable`일 수 있습니다.
+감사 명령은 기본적으로 너무 큰 대화 기록 파일과 JSONL 기록을 건너뛰고(`--max-file-bytes`, `--max-line-bytes`), 건너뛴 개수를 함께 보고합니다. 손상된 추적 기록이 메모리를 독점하거나 스캔 공백을 숨기지 않도록 하기 위한 방어입니다. JSON 출력에는 `cache_friendliness`와 [`cache_diagnostics`](docs/cache-diagnostics-schema.md)도 포함됩니다. 이는 제한된 사용량 필드, timestamped cache telemetry records, 가림 처리된 segment hash로 만든 휴리스틱 프롬프트 배치/cache-read 진단입니다. sibling `cache_layout_advice`는 이 신호를 긴 세션 분리, prefix 안정화 같은 순위화된 **확인/실험**으로 바꾸되, 관측된 issue와 가설/입증된 cause를 분리합니다. 원문 프롬프트는 출력하지 않고 provider cache hit를 증명하지 않으며, 대화 기록 스키마가 충분한 증거를 드러내지 않으면 `missing`, `partial`, `hypothesis`, `unavailable`일 수 있습니다.
 
 ### 상태표시줄에서 컨텍스트와 캐시 상태 확인
 

package/README.md

@@ -99,7 +99,7 @@ When you need a savings claim, measure it on your own tasks:
 
 - full-file reads versus symbol or line-range reads
 - raw logs versus digest output or artifact receipts
-- transcript hotspots reported by `context-guard-audit`, including `cache_friendliness` prompt-layout signals
+- transcript hotspots reported by `context-guard-audit`, including `cache_friendliness` prompt-layout signals and `cache_layout_advice` experiment priorities
 - statusline `cache` / `reuse` as observed transcript/provider-cache signals, not savings caused by ContextGuard
 - `context-guard cost preflight` estimates for Anthropic request JSON, followed by `context-guard cost observe` using provider usage fields (`cache_creation_input_tokens`, `cache_read_input_tokens`) after the call
 - matched successful baseline/variant runs from `context-guard-bench`
@@ -339,7 +339,7 @@ JSON
 ./plugins/context-guard/bin/context-guard-audit ~/.claude/projects --top 20 --recommend
 ```
 
-The audit command skips oversized transcript files and JSONL records by default (`--max-file-bytes`, `--max-line-bytes`) and reports skipped counts, so a corrupt trace cannot dominate memory or hide scan gaps. JSON output also includes `cache_friendliness` and [`cache_diagnostics`](docs/cache-diagnostics-schema.md): heuristic prompt-layout/cache-read diagnostics built from bounded usage fields, timestamped cache telemetry records, and redacted segment hashes. They can flag likely volatile content near the prompt prefix, stable-prefix candidates, cache-miss hypotheses, and TTL/headroom evidence gaps, but they do not print raw prompt text, do not prove provider cache hits, and may be `missing`, `partial`, `hypothesis`, or `unavailable` when transcript schemas do not expose enough evidence.
+The audit command skips oversized transcript files and JSONL records by default (`--max-file-bytes`, `--max-line-bytes`) and reports skipped counts, so a corrupt trace cannot dominate memory or hide scan gaps. JSON output also includes `cache_friendliness` and [`cache_diagnostics`](docs/cache-diagnostics-schema.md): heuristic prompt-layout/cache-read diagnostics built from bounded usage fields, timestamped cache telemetry records, and redacted segment hashes. The sibling `cache_layout_advice` field turns those signals into ranked **checks/experiments** such as splitting long sessions or stabilizing early prompt prefixes, while keeping observed issues separate from hypothesized or corroborated causes. These fields can flag likely volatile content near the prompt prefix, stable-prefix candidates, cache-miss hypotheses, and TTL/headroom evidence gaps, but they do not print raw prompt text, do not prove provider cache hits, and may be `missing`, `partial`, `hypothesis`, or `unavailable` when transcript schemas do not expose enough evidence.
 
 ### Watch context and cache health in the statusline
 

package/context-guard-kit/README.md

@@ -65,7 +65,7 @@ python3 context-guard-kit/sanitize_output.py -- git diff
 `../research/experimental-token-reduction-radar.md`는 learned compression, multimodal crop/OCR/visual-token pruning, self-hosted KV/latent inference optimization 같은 선택적 미래 실험을 문서화한 gate입니다. `../docs/experimental-benchmark-fixtures.md`에는 fixture-only task/variant 시작 예시가 있습니다. 이 radar와 fixture는 현재 제공되는 runtime helper가 아니며, hosted API token/cost 절감을 보장하지 않습니다. hosted API token/cost 절감 주장은 provider가 측정한 matched-task 근거가 있을 때만 허용합니다. Radar의 later-roadmap gate는 neural/semantic compression, trust-tiered injection-aware compression, context-diff compaction, local proxy constraint를 별도 미래 PR이 gate를 통과하기 전까지 experimental/non-shipped로 유지합니다.
 
 `claude_transcript_cost_audit.py --recommend`의 기본 출력은 공유 시 안전하도록 transcript 경로를 `basename#hash`, 명령을 `command#hash` 형태로 익명화합니다. 로컬 원문 식별자가 꼭 필요할 때만 `--show-paths` 또는 `--show-commands`를 추가하세요.
-대용량/손상 transcript 방어를 위해 파일 단위 `--max-file-bytes`, JSONL record 단위 `--max-line-bytes` 제한도 기본 적용되며, 건너뛴 항목은 skip count와 warning으로 표시됩니다. JSON summary/feasibility 출력의 `cache_friendliness`는 제한된 정제 segment hash로 안정적인 prefix와 volatile prefix/tail 신호를 비교하는 휴리스틱입니다. 원문 prompt text는 출력하지 않고, provider cache token field는 ContextGuard가 만든 토큰 절감 증거가 아니라 별도 진단 텔레메트리로 해석하세요.
+대용량/손상 transcript 방어를 위해 파일 단위 `--max-file-bytes`, JSONL record 단위 `--max-line-bytes` 제한도 기본 적용되며, 건너뛴 항목은 skip count와 warning으로 표시됩니다. JSON summary/feasibility 출력의 `cache_friendliness`는 제한된 정제 segment hash로 안정적인 prefix와 volatile prefix/tail 신호를 비교하는 휴리스틱입니다. `cache_layout_advice`는 그 신호를 긴 세션 분리, prefix 안정화, diet 점검 같은 순위화된 확인/실험으로 연결하지만, 관측 issue와 가설/입증 cause를 분리합니다. 원문 prompt text는 출력하지 않고, provider cache token field는 ContextGuard가 만든 토큰 절감 증거가 아니라 별도 진단 텔레메트리로 해석하세요.
 
 `context_guard_diet.py scan`은 항상 로컬에서만 읽는 read-only 스캐너입니다. 기본 출력은 project root를 익명화하고 상대경로 중심으로 보고합니다. `--top`은 보고서의 context-like file 목록과 context-exclusion recommendation 목록에 공통으로 적용됩니다. `--show-paths`는 로컬/비공개 디버깅에서만 쓰세요.
 

package/context-guard-kit/claude_transcript_cost_audit.py

@@ -49,6 +49,7 @@ TIMESTAMP_KEYS = ("timestamp", "created_at", "createdAt", "time", "ts")
 FEASIBILITY_SCHEMA_VERSION = "contextguard.metric-feasibility.v1.2"
 FEASIBILITY_PRODUCER = "context-guard-audit"
 CACHE_DIAGNOSTICS_SCHEMA_VERSION = "contextguard.cache-diagnostics.v1"
+CACHE_LAYOUT_ADVICE_SCHEMA_VERSION = "contextguard.cache-layout-advice.v1"
 MAX_ERROR_EXAMPLES = 20
 JSON_PARSE_RECURSION_LIMIT = 10_000
 READ_CHUNK_BYTES = 64 * 1024
@@ -184,6 +185,7 @@ class UsageSummary:
     prompt_cache_audit: PromptCacheAudit = field(default_factory=PromptCacheAudit)
     cache_friendliness_cache: dict[str, Any] | None = field(default=None, init=False, repr=False)
     cache_diagnostics_cache: dict[str, Any] | None = field(default=None, init=False, repr=False)
+    cache_layout_advice_cache: dict[str, Any] | None = field(default=None, init=False, repr=False)
 
     @property
     def total_tokens(self) -> int:
@@ -1398,6 +1400,222 @@ def cache_diagnostics_for_summary(summary: UsageSummary) -> dict[str, Any]:
     return build_cache_diagnostics(summary)
 
 
+def _dominant_transcript(summary: UsageSummary) -> dict[str, Any] | None:
+    if summary.total_tokens <= 0 or not summary.by_file:
+        return None
+    _label, tokens = summary.by_file.most_common(1)[0]
+    share = tokens / summary.total_tokens if summary.total_tokens else 0.0
+    return {
+        "tokens": tokens,
+        "share": round(share, 4),
+        "dominates": share >= 0.20 and tokens >= 1_000,
+    }
+
+
+def _first_dynamic_breaker(cache_diagnostics: dict[str, Any]) -> dict[str, Any] | None:
+    breakers = cache_diagnostics.get("dynamic_prefix_breakers") or []
+    if not breakers:
+        return None
+    first = breakers[0]
+    return first if isinstance(first, dict) else None
+
+
+def build_cache_layout_advice(summary: UsageSummary) -> dict[str, Any]:
+    if summary.cache_layout_advice_cache is not None:
+        return summary.cache_layout_advice_cache
+
+    cache_friendliness = cache_friendliness_for_summary(summary)
+    cache_diagnostics = cache_diagnostics_for_summary(summary)
+    signals = cache_friendliness.get("signals") if isinstance(cache_friendliness.get("signals"), dict) else {}
+    dynamic_breaker = _first_dynamic_breaker(cache_diagnostics)
+    dominant = _dominant_transcript(summary)
+    cache_creation = summary.tokens.get("cache_creation", 0)
+    cache_read = summary.tokens.get("cache_read", 0)
+    cache_fields = cache_diagnostics.get("observations", {}).get("cache_fields", {}) if isinstance(cache_diagnostics.get("observations"), dict) else {}
+    cache_status = cache_fields.get("status") if isinstance(cache_fields, dict) else None
+    stable_prefix_share = signals.get("stable_prefix_share")
+    volatile_prefix_share = signals.get("volatile_prefix_share")
+    volatile_tail_share = signals.get("volatile_tail_share")
+    max_prefix_position = dynamic_breaker.get("position") if dynamic_breaker else None
+    max_prefix_position_volatile_share = dynamic_breaker.get("volatile_share") if dynamic_breaker else signals.get("max_prefix_position_volatile_share")
+
+    status = "missing"
+    confidence = "unavailable"
+    observed_issue = "unknown"
+    priority = "P2"
+    hypothesized_causes: list[dict[str, Any]] = []
+    corroborated_causes: list[dict[str, Any]] = []
+    next_checks: list[dict[str, Any]] = []
+    recommended_experiments: list[dict[str, Any]] = []
+
+    has_cache_any = bool(
+        summary.token_field_presence.get("cache_read", 0)
+        or summary.token_field_presence.get("cache_creation", 0)
+    )
+    has_prompt_samples = bool(summary.prompt_cache_audit.samples)
+    if has_cache_any or has_prompt_samples:
+        status = "partial" if (
+            not has_prompt_samples
+            or cache_friendliness.get("status") == "partial"
+            or cache_diagnostics.get("status") == "partial"
+            or summary.skipped_files
+            or summary.skipped_records
+            or summary.parse_errors
+        ) else "available"
+        confidence = "partial" if status == "partial" else "hypothesis"
+
+    volatile_prefix_breaker = bool(
+        dynamic_breaker
+        and cache_creation > 0
+        and (max_prefix_position in {0, 1} or (max_prefix_position_volatile_share or 0) >= PROMPT_PREFIX_VOLATILE_THRESHOLD)
+    )
+    long_session_dominates = bool(dominant and dominant.get("dominates"))
+
+    if volatile_prefix_breaker:
+        observed_issue = "volatile_prefix_breaker"
+        priority = "P0" if cache_creation >= 50_000 and max_prefix_position in {0, 1} else "P1"
+        hypothesized_causes.append({
+            "id": "prefix-position-churn",
+            "confidence": confidence,
+            "evidence": EVIDENCE_INFERRED,
+            "reason": (
+                "A highly volatile redacted prompt segment appears in the early prefix window; "
+                "this identifies a layout issue, not a confirmed source."
+            ),
+            "next_check": "Check whether startup context, generated evidence, or tool/MCP catalog changes are moving before stable policy.",
+        })
+        if cache_diagnostics.get("stable_prefix_candidates"):
+            hypothesized_causes.append({
+                "id": "evidence-before-policy",
+                "confidence": confidence,
+                "evidence": EVIDENCE_INFERRED,
+                "reason": (
+                    "Stable reusable segments appear elsewhere while the early prefix churns; "
+                    "check whether logs, diffs, timestamps, or file evidence precede stable instructions."
+                ),
+                "next_check": "Keep stable policy/instructions first and move generated run evidence later.",
+            })
+        next_checks.append({
+            "id": "inspect-startup-context-size",
+            "confidence": "hypothesis",
+            "command_templates": [
+                "context-guard-diet scan <repo>",
+                "context-guard-diet structural-waste <repo>",
+            ],
+            "evidence_required_for_corroboration": (
+                "Large or duplicate CLAUDE.md/AGENTS.md/GEMINI.md findings from diet output."
+            ),
+        })
+    elif long_session_dominates:
+        observed_issue = "long_session_accumulation"
+        priority = "P1"
+    elif cache_creation >= 10_000 and cache_read > 0 and summary.cache_amortization < 0.5:
+        observed_issue = "low_cache_reuse"
+        priority = "P1"
+    elif cache_status == "missing" or not has_cache_any:
+        observed_issue = "missing_cache_fields"
+        priority = "P2"
+
+    if long_session_dominates:
+        recommended_experiments.append({
+            "id": "split-long-sessions",
+            "order": len(recommended_experiments) + 1,
+            "priority": "P1",
+            "effort": "low",
+            "action": "Use /clear between unrelated tasks and /compact focus on changed files, failing tests, and remaining TODO during long work.",
+            "expected_signal": "Cache creation per comparable task decreases and one transcript no longer dominates observed tokens.",
+            "verification": "Re-run context-guard-audit on a comparable window and compare cache_creation, cache_amortization, and top transcript share.",
+            "evidence": dominant or {},
+        })
+    if volatile_prefix_breaker:
+        recommended_experiments.append({
+            "id": "stabilize-cache-prefix",
+            "order": len(recommended_experiments) + 1,
+            "priority": priority,
+            "effort": "medium",
+            "action": "Keep stable reusable instructions/policy before volatile logs, diffs, timestamps, and generated file evidence.",
+            "expected_signal": "Stable prefix share rises and volatile prefix share falls on matched audit windows.",
+            "verification": "Re-run context-guard-audit --json --recommend and compare cache_layout_advice plus cache_friendliness signals.",
+            "evidence": {
+                "dynamic_prefix_breaker_position": max_prefix_position,
+                "dynamic_prefix_breaker_volatile_share": max_prefix_position_volatile_share,
+            },
+        })
+        recommended_experiments.append({
+            "id": "run-context-diet-checks",
+            "order": len(recommended_experiments) + 1,
+            "priority": "P1",
+            "effort": "low",
+            "action": "Run the generated diet command templates and treat any large/duplicate context-file findings as corroborating evidence before editing instructions.",
+            "expected_signal": "Diet output identifies or rules out oversized/duplicated startup context as a contributor.",
+            "verification": "Record diet JSON separately; do not convert prefix-position evidence alone into a confirmed startup-context cause.",
+            "command_templates": [
+                "context-guard-diet scan <repo> --json > diet.json",
+                "context-guard-diet structural-waste <repo> --json > structural-waste.json",
+            ],
+        })
+    if cache_creation >= 50_000 and summary.cache_amortization_defined and 1.0 <= summary.cache_amortization < 5.0:
+        recommended_experiments.append({
+            "id": "defer-longer-ttl-until-prefix-stable" if volatile_prefix_breaker else "evaluate-longer-ttl-after-stability-check",
+            "order": len(recommended_experiments) + 1,
+            "priority": "P2",
+            "effort": "medium",
+            "action": "Treat longer TTL as secondary; first corroborate stable prefix reuse and current provider TTL/pricing behavior.",
+            "expected_signal": "TTL evaluation happens only after prefix volatility is reduced or ruled out.",
+            "verification": "Use timestamped cache telemetry and provider-measured billing/cost evidence; historical token totals alone are insufficient.",
+        })
+    if not recommended_experiments and status == "partial":
+        next_checks.append({
+            "id": "rerun-narrower-audit",
+            "confidence": "partial",
+            "command_templates": ["context-guard-audit <transcript-or-project-dir> --json --recommend"],
+            "evidence_required_for_corroboration": "Enough uncapped prompt/cache records to classify prefix layout.",
+        })
+    if not recommended_experiments and observed_issue == "missing_cache_fields":
+        next_checks.append({
+            "id": "collect-cache-telemetry",
+            "confidence": "unavailable",
+            "command_templates": ["context-guard-audit ~/.claude/projects --json --recommend"],
+            "evidence_required_for_corroboration": "Transcript records with cache_read/cache_creation fields.",
+        })
+
+    advice = {
+        "schema_version": CACHE_LAYOUT_ADVICE_SCHEMA_VERSION,
+        "status": status,
+        "confidence": confidence,
+        "heuristic": True,
+        "observed_issue": observed_issue,
+        "priority": priority,
+        "observed_summary": {
+            "cache_creation_tokens": cache_creation,
+            "cache_read_tokens": cache_read,
+            "cache_amortization": round(summary.cache_amortization, 4) if summary.cache_amortization_defined else None,
+            "stable_prefix_share": stable_prefix_share,
+            "volatile_prefix_share": volatile_prefix_share,
+            "volatile_tail_share": volatile_tail_share,
+            "max_prefix_position": max_prefix_position,
+            "max_prefix_position_volatile_share": max_prefix_position_volatile_share,
+            "dominant_transcript_share": dominant.get("share") if dominant else None,
+        },
+        "hypothesized_causes": hypothesized_causes,
+        "corroborated_causes": corroborated_causes,
+        "next_checks": next_checks,
+        "recommended_experiments": recommended_experiments,
+        "caveats": [
+            "Cache layout advice is a local transcript heuristic, not billing authority or provider-cache proof.",
+            "Observed issues come from cache fields and redacted segment statistics; causes remain hypotheses until corroborated by diet/structural evidence.",
+            "Generated command templates use placeholders and must not be treated as observed user commands or paths.",
+            "Use matched before/after audits before making token or cost savings claims.",
+        ],
+    }
+    summary.cache_layout_advice_cache = advice
+    return advice
+
+
+def cache_layout_advice_for_summary(summary: UsageSummary) -> dict[str, Any]:
+    return build_cache_layout_advice(summary)
+
+
 def build_metric_caveats(summary: UsageSummary) -> list[str]:
     caveats = [
         "Values are observed from local Claude Code transcript JSON/JSONL fields and are not official billing records.",
@@ -1433,6 +1651,7 @@ def feasibility_json(
     stable_total_tokens = sum(stable_tokens.values())
     cache_friendliness = cache_friendliness_for_summary(summary)
     cache_diagnostics = cache_diagnostics_for_summary(summary)
+    cache_layout_advice = cache_layout_advice_for_summary(summary)
     return {
         "schema_version": FEASIBILITY_SCHEMA_VERSION,
         "producer": FEASIBILITY_PRODUCER,
@@ -1452,6 +1671,7 @@ def feasibility_json(
                 "headroom_availability",
                 "cache_friendliness",
                 "cache_diagnostics",
+                "cache_layout_advice",
                 "totals",
             ],
             "diagnostic_fields": ["summary"],
@@ -1480,6 +1700,7 @@ def feasibility_json(
         "headroom_availability": availability["headroom"],
         "cache_friendliness": cache_friendliness,
         "cache_diagnostics": cache_diagnostics,
+        "cache_layout_advice": cache_layout_advice,
         "totals": {
             "total_tokens": stable_total_tokens,
             "tokens": stable_tokens,
@@ -1531,6 +1752,36 @@ def build_recommendations(summary: UsageSummary, top: int) -> list[dict[str, Any
     input_ratio = input_tokens / total
     cache_friendliness = cache_friendliness_for_summary(summary)
     cache_diagnostics = cache_diagnostics_for_summary(summary)
+    cache_layout_advice = cache_layout_advice_for_summary(summary)
+    if cache_layout_advice.get("observed_issue") == "volatile_prefix_breaker":
+        evidence = {
+            "observed_issue": cache_layout_advice.get("observed_issue"),
+            "priority": cache_layout_advice.get("priority"),
+            "confidence": cache_layout_advice.get("confidence"),
+            "cache_creation_tokens": cache_creation,
+            "cache_read_tokens": cache_read,
+        }
+        observed_summary = cache_layout_advice.get("observed_summary")
+        if isinstance(observed_summary, dict):
+            for key in ("max_prefix_position", "max_prefix_position_volatile_share", "stable_prefix_share", "volatile_prefix_share"):
+                evidence[key] = observed_summary.get(key)
+        rec = recommendation(
+            "prioritize-cache-prefix-stabilization",
+            "Prioritize cache-prefix stabilization before TTL or output trimming",
+            (
+                "Cache creation remains material and redacted segment statistics show a volatile early prefix; "
+                "this is an experiment-prioritization signal, not a confirmed root cause."
+            ),
+            (
+                "If one transcript dominates, split unrelated work into shorter sessions; then check startup/context "
+                "size and keep stable policy before volatile logs, diffs, timestamps, and generated evidence."
+            ),
+            str(cache_layout_advice.get("priority") or "P1"),
+            evidence,
+        )
+        rec["heuristic"] = True
+        rec["confidence"] = cache_layout_advice.get("confidence")
+        recs.append(rec)
     for finding in cache_friendliness.get("findings", []):
         if isinstance(finding, dict) and finding.get("id") == "volatile-content-near-prefix":
             evidence = dict(finding.get("evidence") or {})
@@ -1754,6 +2005,7 @@ def summary_json(
         "top_tools": counter_json(summary.by_tool, top),
         "cache_friendliness": cache_friendliness_for_summary(summary),
         "cache_diagnostics": cache_diagnostics_for_summary(summary),
+        "cache_layout_advice": cache_layout_advice_for_summary(summary),
     }
     if include_recommendations:
         data["recommendations"] = build_recommendations(summary, top)
@@ -1887,6 +2139,26 @@ def main() -> int:
     headroom = cache_diagnostics.get("headroom_diagnostics") or {}
     print(f"  headroom_status         {headroom.get('status')} ({headroom.get('evidence')})")
 
+    cache_layout_advice = cache_layout_advice_for_summary(summary)
+    if cache_layout_advice.get("status") != "missing" or cache_layout_advice.get("observed_issue") != "unknown":
+        print("\nCache layout advice")
+        print(f"  status                  {cache_layout_advice.get('status')}")
+        print(f"  confidence              {cache_layout_advice.get('confidence')}")
+        print(f"  observed_issue          {cache_layout_advice.get('observed_issue')}")
+        print(f"  priority                {cache_layout_advice.get('priority')}")
+        experiments = cache_layout_advice.get("recommended_experiments") or []
+        if experiments:
+            first = experiments[0]
+            print(f"  first_experiment        {first.get('id')} ({first.get('priority')})")
+            print(f"  experiment_action       {first.get('action')}")
+        checks = cache_layout_advice.get("next_checks") or []
+        if checks:
+            first = checks[0]
+            print(f"  next_check              {first.get('id')}")
+            templates = first.get("command_templates") or []
+            if templates:
+                print(f"  command_template        {templates[0]}")
+
     model_totals = Counter({model: sum(tokens.values()) for model, tokens in summary.by_model.items()})
     print_counter("By model", model_totals, args.top)
 

package/docs/cache-diagnostics-schema.md

@@ -2,7 +2,9 @@
 
 `cache_diagnostics` is the nested diagnostic object emitted by `context-guard-audit --json` and by top-level `cache_diagnostics` in `context-guard-audit --feasibility-json`. The committed schema file, [`cache-diagnostics.schema.json`](cache-diagnostics.schema.json), describes that nested object only; it is not the full CLI response envelope.
 
-The object is for GUI and external consumers that need stable cache-read, prefix-layout, TTL-evidence, and headroom-boundary fields without scraping prose. It is a local transcript diagnostic contract, not a billing source, not provider telemetry verification, and not a token or cost savings promise.
+The object is for GUI and external consumers that need stable cache-read, prefix-layout, TTL-evidence, and headroom-boundary fields without scraping prose. It is a local transcript diagnostic contract, not a billing source, not provider telemetry verification, and not a token or cost savings promise. It does not guarantee savings, does not prove provider cache hits, and does not infer live headroom.
+
+`context-guard-audit` also emits a top-level sibling `cache_layout_advice` object. That sibling is intentionally separate from `cache_diagnostics`: diagnostics stay evidence-oriented, while advice ranks checks and experiments such as session splitting, prefix stabilization, and context-diet scans. Advice distinguishes an `observed_issue` from `hypothesized_causes`, `corroborated_causes`, and `next_checks`; without diet or structural evidence, volatile prefix positions should be presented as hypotheses to check, not confirmed root causes.
 
 ## Files
 
@@ -13,11 +15,30 @@ The object is for GUI and external consumers that need stable cache-read, prefix
 
 ### `context-guard-audit --json`
 
-The legacy audit JSON includes top-level `cache_diagnostics` beside `cache_metrics` and `cache_friendliness`.
+The legacy audit JSON includes top-level `cache_diagnostics` beside `cache_metrics`, `cache_friendliness`, and the separate `cache_layout_advice` advice object.
 
 ### `context-guard-audit --feasibility-json`
 
-The feasibility JSON includes top-level `cache_diagnostics` and lists `cache_diagnostics` in `consumer_contract.stable_top_level_fields`. GUI consumers should prefer the top-level feasibility field when available and use `summary.cache_diagnostics` only for legacy compatibility.
+The feasibility JSON includes top-level `cache_diagnostics` and `cache_layout_advice`, and lists both in `consumer_contract.stable_top_level_fields`. GUI consumers should prefer the top-level feasibility field when available and use `summary.cache_diagnostics` only for legacy compatibility.
+
+## Sibling `cache_layout_advice` fields
+
+`cache_layout_advice` is a stable top-level sibling of `cache_diagnostics`, but it is deliberately not part of `cache-diagnostics.schema.json`. It is an advice contract over local transcript heuristics.
+
+| Field | Meaning | Consumer note |
+| --- | --- | --- |
+| `schema_version` | Stable version string, currently `contextguard.cache-layout-advice.v1`. | Treat unknown versions conservatively. |
+| `status` | Advice availability: `available`, `partial`, or `missing`. | `partial` means prompt/cache evidence was capped, skipped, or incomplete. |
+| `confidence` | Overall advice confidence: `hypothesis`, `partial`, or `unavailable`. | Never present as provider truth or billing proof. |
+| `heuristic` | Always `true` for v1. | UI should label advice as heuristic. |
+| `observed_issue` | Primary observed layout issue: `volatile_prefix_breaker`, `long_session_accumulation`, `low_cache_reuse`, `missing_cache_fields`, or `unknown`. | This is an observed/audited symptom, not a confirmed cause. |
+| `priority` | Suggested priority bucket (`P0`, `P1`, or `P2`). | Use for ordering checks, not for savings claims. |
+| `observed_summary` | Sanitized numeric summary such as cache creation/read tokens, prefix shares, breaker position, and dominant transcript share. | Contains aggregate counts/shares only, not raw prompt text. |
+| `hypothesized_causes` | Candidate causes to investigate, each with `id`, `confidence`, `evidence`, `reason`, and `next_check`. | Keep separate from confirmed causes. |
+| `corroborated_causes` | Causes supported by independent evidence beyond prefix-position heuristics. | Empty means no cause has been confirmed. |
+| `next_checks` | Evidence-gathering checks with `id`, `confidence`, `command_templates`, and `evidence_required_for_corroboration`. | Templates use placeholders such as `<repo>` and must not embed observed local paths. |
+| `recommended_experiments` | Ordered experiments with `id`, `order`, `priority`, `effort`, `action`, `expected_signal`, and `verification`. | Run in `order`; compare matched audit windows before claiming improvement. |
+| `caveats` | User-facing boundaries for claims and evidence limits. | Preserve these in GUI summaries and reports. |
 
 ## Top-level fields
 
@@ -72,4 +93,4 @@ Historical transcript scans do not carry live context-window state. `headroom_di
 
 ## Claim boundaries
 
-`cache_diagnostics` can help users reorganize prompts, find volatile prefix segments, and identify missing evidence. It does not guarantee savings, does not verify provider cache state, is not billing authority, does not prove provider cache hits, and does not infer live headroom from historical token totals.
+`cache_diagnostics` and the sibling `cache_layout_advice` can help users reorganize prompts, find volatile prefix segments, and identify missing evidence or next checks. They do not guarantee savings, do not verify provider cache state, are not billing authority, do not prove provider cache hits, and do not infer live headroom from historical token totals.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ictechgy/context-guard",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "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",

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

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

@@ -95,7 +95,7 @@ context-guard-statusline-merged
 - **출력 축약기**는 감싼 명령의 종료 코드를 보존하면서 긴 로그를 줄이고, `--digest markdown` 또는 `--digest json`으로 실행기 실패 정보, 가림 처리된 failure signature, 중복 라인 그룹, 다음 조회 제안이 담긴 요약을 만들 수 있습니다.
 - **민감정보 가림 도구**는 검색, diff, 로그 출력에서 자격 증명 패턴, 비공개 키 블록, 인증 헤더, 자격 증명이 포함된 URL, 민감해 보이는 경로를 가립니다.
 - **상태표시줄**은 모델, 컨텍스트, 비용 신호를 짧게 보여주고, 대화 기록 데이터가 있으면 캐시 읽기와 캐시 재사용 신호도 함께 표시합니다.
-- **대화 기록 감사**는 usage/cost/cache bucket을 집계하고, 토큰 집중 지점과 `cache_friendliness` 프롬프트 배치 신호를 제한된 가림 처리된 segment hash로 보고합니다. 원문 프롬프트는 출력하지 않습니다.
+- **대화 기록 감사**는 usage/cost/cache bucket을 집계하고, 토큰 집중 지점, `cache_friendliness` 프롬프트 배치 신호, `cache_layout_advice` 확인/실험 우선순위를 제한된 가림 처리된 segment hash로 보고합니다. 원문 프롬프트는 출력하지 않습니다.
 - **반복 실패 알림**은 Bash 실패가 반복될 때 같은 경로를 계속 재시도하지 않고 전략을 바꾸도록 안내합니다.
 - **벤치마크 헬퍼**는 기준/변형 실행을 대응해 실제 토큰·비용 필드, 별도의 바이트 감소 간접 증거, 진단용 `wall_time_seconds`, `provider_cached_tokens`, provider-cache 사용 가능성 텔레메트리로 기록합니다.
 
@@ -109,7 +109,7 @@ brief 모드는 코딩 에이전트가 군더더기를 줄이도록 요청하되
 
 ## 절감 수치를 과장하지 않습니다
 
-이 헬퍼들은 흔히 컨텍스트를 불필요하게 키우는 원인을 줄이지만, 고정된 절감률을 보장하지 않습니다. 실제 전후 비교 증거가 필요하면 `context-guard-bench --ledger-jsonl ... --report-json ...`로 본인 작업에서 측정하세요. 토큰 절감 주장은 대응 태스크 양쪽 모두에 `primary_tokens_measured`가 있을 때만 계산하며, report의 `matched_pair_evidence`가 성공한 baseline/variant task bucket을 transform, quality gate, 측정 가능 여부, claim boundary와 연결합니다. wall-time과 provider-cache 필드는 진단용 텔레메트리이지 단독 절감 증거가 아닙니다. 감사의 `cache_friendliness`와 [`cache_diagnostics`](https://github.com/ictechgy/context-guard/blob/main/docs/cache-diagnostics-schema.md)는 관측/추론/가설/불가 경계를 둔 휴리스틱 배치·cache-read 신호이며 청구 기준이나 provider-cache 증명이 아닙니다. 벤치마크 CSV 스키마는 엄격하므로 헬퍼 업그레이드 후에는 새 CSV를 시작하거나 헤더를 마이그레이션하세요. 작업 유형별 합성 예시는 [`docs/benchmark-workflow-examples.md`](https://github.com/ictechgy/context-guard/blob/main/docs/benchmark-workflow-examples.md)에 있고, fixture-only 실험 시작 예시는 [`docs/experimental-benchmark-fixtures.md`](https://github.com/ictechgy/context-guard/blob/main/docs/experimental-benchmark-fixtures.md)에 있습니다.
+이 헬퍼들은 흔히 컨텍스트를 불필요하게 키우는 원인을 줄이지만, 고정된 절감률을 보장하지 않습니다. 실제 전후 비교 증거가 필요하면 `context-guard-bench --ledger-jsonl ... --report-json ...`로 본인 작업에서 측정하세요. 토큰 절감 주장은 대응 태스크 양쪽 모두에 `primary_tokens_measured`가 있을 때만 계산하며, report의 `matched_pair_evidence`가 성공한 baseline/variant task bucket을 transform, quality gate, 측정 가능 여부, claim boundary와 연결합니다. wall-time과 provider-cache 필드는 진단용 텔레메트리이지 단독 절감 증거가 아닙니다. 감사의 `cache_friendliness`, [`cache_diagnostics`](https://github.com/ictechgy/context-guard/blob/main/docs/cache-diagnostics-schema.md), `cache_layout_advice`는 관측/추론/가설/불가 경계를 둔 휴리스틱 배치·cache-read 신호와 순위화된 확인/실험이며 청구 기준이나 provider-cache 증명이 아닙니다. 벤치마크 CSV 스키마는 엄격하므로 헬퍼 업그레이드 후에는 새 CSV를 시작하거나 헤더를 마이그레이션하세요. 작업 유형별 합성 예시는 [`docs/benchmark-workflow-examples.md`](https://github.com/ictechgy/context-guard/blob/main/docs/benchmark-workflow-examples.md)에 있고, fixture-only 실험 시작 예시는 [`docs/experimental-benchmark-fixtures.md`](https://github.com/ictechgy/context-guard/blob/main/docs/experimental-benchmark-fixtures.md)에 있습니다.
 
 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.
 

package/plugins/context-guard/README.md

@@ -101,7 +101,7 @@ context-guard-statusline-merged
 - **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 and re-expand omitted slices with the emitted `context-guard-artifact get ...` command.
 - **Sanitizer** redacts common credential patterns, private key blocks, auth headers, credential URLs, and sensitive-looking paths from search, diff, and log output.
 - **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` plus additive [`cache_diagnostics`](https://github.com/ictechgy/context-guard/blob/main/docs/cache-diagnostics-schema.md) findings from bounded usage fields, timestamped cache telemetry records, and redacted segment hashes without printing raw prompt text or claiming provider-cache savings.
+- **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.
 
@@ -115,7 +115,7 @@ Three deterministic levels — `lite`, `standard`, `ultra` — live under [`brie
 
 ## Conservative claims
 
-These helpers reduce common sources of context bloat, but they do not guarantee a fixed percentage savings. Use `context-guard-bench --ledger-jsonl ... --report-json ...` when you need measured before/after evidence for your own tasks; token-savings claims require `primary_tokens_measured` on both matched sides, and the report's `matched_pair_evidence` links each successful baseline/variant task bucket to the transform, quality gate, measurement availability, and claim boundary. Wall-time/provider-cache fields are diagnostic telemetry, not standalone savings proof. Audit `cache_friendliness` and [`cache_diagnostics`](https://github.com/ictechgy/context-guard/blob/main/docs/cache-diagnostics-schema.md) findings are heuristic layout/cache-read signals with observed/inferred/hypothesis/unavailable boundaries, not billing authority or provider-cache proof. Benchmark CSV schemas are strict, so start a new CSV or migrate the header after helper upgrades. Workflow-specific synthetic examples live in [`docs/benchmark-workflow-examples.md`](https://github.com/ictechgy/context-guard/blob/main/docs/benchmark-workflow-examples.md), and fixture-only experimental task/variant starters live in [`docs/experimental-benchmark-fixtures.md`](https://github.com/ictechgy/context-guard/blob/main/docs/experimental-benchmark-fixtures.md).
+These helpers reduce common sources of context bloat, but they do not guarantee a fixed percentage savings. Use `context-guard-bench --ledger-jsonl ... --report-json ...` when you need measured before/after evidence for your own tasks; token-savings claims require `primary_tokens_measured` on both matched sides, and the report's `matched_pair_evidence` links each successful baseline/variant task bucket to the transform, quality gate, measurement availability, and claim boundary. Wall-time/provider-cache fields are diagnostic telemetry, not standalone savings proof. Audit `cache_friendliness`, [`cache_diagnostics`](https://github.com/ictechgy/context-guard/blob/main/docs/cache-diagnostics-schema.md), and `cache_layout_advice` findings are heuristic layout/cache-read signals and ranked checks/experiments with observed/inferred/hypothesis/unavailable boundaries, not billing authority or provider-cache proof. Benchmark CSV schemas are strict, so start a new CSV or migrate the header after helper upgrades. Workflow-specific synthetic examples live in [`docs/benchmark-workflow-examples.md`](https://github.com/ictechgy/context-guard/blob/main/docs/benchmark-workflow-examples.md), and fixture-only experimental task/variant starters live in [`docs/experimental-benchmark-fixtures.md`](https://github.com/ictechgy/context-guard/blob/main/docs/experimental-benchmark-fixtures.md).
 
 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.
 

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

@@ -49,6 +49,7 @@ TIMESTAMP_KEYS = ("timestamp", "created_at", "createdAt", "time", "ts")
 FEASIBILITY_SCHEMA_VERSION = "contextguard.metric-feasibility.v1.2"
 FEASIBILITY_PRODUCER = "context-guard-audit"
 CACHE_DIAGNOSTICS_SCHEMA_VERSION = "contextguard.cache-diagnostics.v1"
+CACHE_LAYOUT_ADVICE_SCHEMA_VERSION = "contextguard.cache-layout-advice.v1"
 MAX_ERROR_EXAMPLES = 20
 JSON_PARSE_RECURSION_LIMIT = 10_000
 READ_CHUNK_BYTES = 64 * 1024
@@ -184,6 +185,7 @@ class UsageSummary:
     prompt_cache_audit: PromptCacheAudit = field(default_factory=PromptCacheAudit)
     cache_friendliness_cache: dict[str, Any] | None = field(default=None, init=False, repr=False)
     cache_diagnostics_cache: dict[str, Any] | None = field(default=None, init=False, repr=False)
+    cache_layout_advice_cache: dict[str, Any] | None = field(default=None, init=False, repr=False)
 
     @property
     def total_tokens(self) -> int:
@@ -1398,6 +1400,222 @@ def cache_diagnostics_for_summary(summary: UsageSummary) -> dict[str, Any]:
     return build_cache_diagnostics(summary)
 
 
+def _dominant_transcript(summary: UsageSummary) -> dict[str, Any] | None:
+    if summary.total_tokens <= 0 or not summary.by_file:
+        return None
+    _label, tokens = summary.by_file.most_common(1)[0]
+    share = tokens / summary.total_tokens if summary.total_tokens else 0.0
+    return {
+        "tokens": tokens,
+        "share": round(share, 4),
+        "dominates": share >= 0.20 and tokens >= 1_000,
+    }
+
+
+def _first_dynamic_breaker(cache_diagnostics: dict[str, Any]) -> dict[str, Any] | None:
+    breakers = cache_diagnostics.get("dynamic_prefix_breakers") or []
+    if not breakers:
+        return None
+    first = breakers[0]
+    return first if isinstance(first, dict) else None
+
+
+def build_cache_layout_advice(summary: UsageSummary) -> dict[str, Any]:
+    if summary.cache_layout_advice_cache is not None:
+        return summary.cache_layout_advice_cache
+
+    cache_friendliness = cache_friendliness_for_summary(summary)
+    cache_diagnostics = cache_diagnostics_for_summary(summary)
+    signals = cache_friendliness.get("signals") if isinstance(cache_friendliness.get("signals"), dict) else {}
+    dynamic_breaker = _first_dynamic_breaker(cache_diagnostics)
+    dominant = _dominant_transcript(summary)
+    cache_creation = summary.tokens.get("cache_creation", 0)
+    cache_read = summary.tokens.get("cache_read", 0)
+    cache_fields = cache_diagnostics.get("observations", {}).get("cache_fields", {}) if isinstance(cache_diagnostics.get("observations"), dict) else {}
+    cache_status = cache_fields.get("status") if isinstance(cache_fields, dict) else None
+    stable_prefix_share = signals.get("stable_prefix_share")
+    volatile_prefix_share = signals.get("volatile_prefix_share")
+    volatile_tail_share = signals.get("volatile_tail_share")
+    max_prefix_position = dynamic_breaker.get("position") if dynamic_breaker else None
+    max_prefix_position_volatile_share = dynamic_breaker.get("volatile_share") if dynamic_breaker else signals.get("max_prefix_position_volatile_share")
+
+    status = "missing"
+    confidence = "unavailable"
+    observed_issue = "unknown"
+    priority = "P2"
+    hypothesized_causes: list[dict[str, Any]] = []
+    corroborated_causes: list[dict[str, Any]] = []
+    next_checks: list[dict[str, Any]] = []
+    recommended_experiments: list[dict[str, Any]] = []
+
+    has_cache_any = bool(
+        summary.token_field_presence.get("cache_read", 0)
+        or summary.token_field_presence.get("cache_creation", 0)
+    )
+    has_prompt_samples = bool(summary.prompt_cache_audit.samples)
+    if has_cache_any or has_prompt_samples:
+        status = "partial" if (
+            not has_prompt_samples
+            or cache_friendliness.get("status") == "partial"
+            or cache_diagnostics.get("status") == "partial"
+            or summary.skipped_files
+            or summary.skipped_records
+            or summary.parse_errors
+        ) else "available"
+        confidence = "partial" if status == "partial" else "hypothesis"
+
+    volatile_prefix_breaker = bool(
+        dynamic_breaker
+        and cache_creation > 0
+        and (max_prefix_position in {0, 1} or (max_prefix_position_volatile_share or 0) >= PROMPT_PREFIX_VOLATILE_THRESHOLD)
+    )
+    long_session_dominates = bool(dominant and dominant.get("dominates"))
+
+    if volatile_prefix_breaker:
+        observed_issue = "volatile_prefix_breaker"
+        priority = "P0" if cache_creation >= 50_000 and max_prefix_position in {0, 1} else "P1"
+        hypothesized_causes.append({
+            "id": "prefix-position-churn",
+            "confidence": confidence,
+            "evidence": EVIDENCE_INFERRED,
+            "reason": (
+                "A highly volatile redacted prompt segment appears in the early prefix window; "
+                "this identifies a layout issue, not a confirmed source."
+            ),
+            "next_check": "Check whether startup context, generated evidence, or tool/MCP catalog changes are moving before stable policy.",
+        })
+        if cache_diagnostics.get("stable_prefix_candidates"):
+            hypothesized_causes.append({
+                "id": "evidence-before-policy",
+                "confidence": confidence,
+                "evidence": EVIDENCE_INFERRED,
+                "reason": (
+                    "Stable reusable segments appear elsewhere while the early prefix churns; "
+                    "check whether logs, diffs, timestamps, or file evidence precede stable instructions."
+                ),
+                "next_check": "Keep stable policy/instructions first and move generated run evidence later.",
+            })
+        next_checks.append({
+            "id": "inspect-startup-context-size",
+            "confidence": "hypothesis",
+            "command_templates": [
+                "context-guard-diet scan <repo>",
+                "context-guard-diet structural-waste <repo>",
+            ],
+            "evidence_required_for_corroboration": (
+                "Large or duplicate CLAUDE.md/AGENTS.md/GEMINI.md findings from diet output."
+            ),
+        })
+    elif long_session_dominates:
+        observed_issue = "long_session_accumulation"
+        priority = "P1"
+    elif cache_creation >= 10_000 and cache_read > 0 and summary.cache_amortization < 0.5:
+        observed_issue = "low_cache_reuse"
+        priority = "P1"
+    elif cache_status == "missing" or not has_cache_any:
+        observed_issue = "missing_cache_fields"
+        priority = "P2"
+
+    if long_session_dominates:
+        recommended_experiments.append({
+            "id": "split-long-sessions",
+            "order": len(recommended_experiments) + 1,
+            "priority": "P1",
+            "effort": "low",
+            "action": "Use /clear between unrelated tasks and /compact focus on changed files, failing tests, and remaining TODO during long work.",
+            "expected_signal": "Cache creation per comparable task decreases and one transcript no longer dominates observed tokens.",
+            "verification": "Re-run context-guard-audit on a comparable window and compare cache_creation, cache_amortization, and top transcript share.",
+            "evidence": dominant or {},
+        })
+    if volatile_prefix_breaker:
+        recommended_experiments.append({
+            "id": "stabilize-cache-prefix",
+            "order": len(recommended_experiments) + 1,
+            "priority": priority,
+            "effort": "medium",
+            "action": "Keep stable reusable instructions/policy before volatile logs, diffs, timestamps, and generated file evidence.",
+            "expected_signal": "Stable prefix share rises and volatile prefix share falls on matched audit windows.",
+            "verification": "Re-run context-guard-audit --json --recommend and compare cache_layout_advice plus cache_friendliness signals.",
+            "evidence": {
+                "dynamic_prefix_breaker_position": max_prefix_position,
+                "dynamic_prefix_breaker_volatile_share": max_prefix_position_volatile_share,
+            },
+        })
+        recommended_experiments.append({
+            "id": "run-context-diet-checks",
+            "order": len(recommended_experiments) + 1,
+            "priority": "P1",
+            "effort": "low",
+            "action": "Run the generated diet command templates and treat any large/duplicate context-file findings as corroborating evidence before editing instructions.",
+            "expected_signal": "Diet output identifies or rules out oversized/duplicated startup context as a contributor.",
+            "verification": "Record diet JSON separately; do not convert prefix-position evidence alone into a confirmed startup-context cause.",
+            "command_templates": [
+                "context-guard-diet scan <repo> --json > diet.json",
+                "context-guard-diet structural-waste <repo> --json > structural-waste.json",
+            ],
+        })
+    if cache_creation >= 50_000 and summary.cache_amortization_defined and 1.0 <= summary.cache_amortization < 5.0:
+        recommended_experiments.append({
+            "id": "defer-longer-ttl-until-prefix-stable" if volatile_prefix_breaker else "evaluate-longer-ttl-after-stability-check",
+            "order": len(recommended_experiments) + 1,
+            "priority": "P2",
+            "effort": "medium",
+            "action": "Treat longer TTL as secondary; first corroborate stable prefix reuse and current provider TTL/pricing behavior.",
+            "expected_signal": "TTL evaluation happens only after prefix volatility is reduced or ruled out.",
+            "verification": "Use timestamped cache telemetry and provider-measured billing/cost evidence; historical token totals alone are insufficient.",
+        })
+    if not recommended_experiments and status == "partial":
+        next_checks.append({
+            "id": "rerun-narrower-audit",
+            "confidence": "partial",
+            "command_templates": ["context-guard-audit <transcript-or-project-dir> --json --recommend"],
+            "evidence_required_for_corroboration": "Enough uncapped prompt/cache records to classify prefix layout.",
+        })
+    if not recommended_experiments and observed_issue == "missing_cache_fields":
+        next_checks.append({
+            "id": "collect-cache-telemetry",
+            "confidence": "unavailable",
+            "command_templates": ["context-guard-audit ~/.claude/projects --json --recommend"],
+            "evidence_required_for_corroboration": "Transcript records with cache_read/cache_creation fields.",
+        })
+
+    advice = {
+        "schema_version": CACHE_LAYOUT_ADVICE_SCHEMA_VERSION,
+        "status": status,
+        "confidence": confidence,
+        "heuristic": True,
+        "observed_issue": observed_issue,
+        "priority": priority,
+        "observed_summary": {
+            "cache_creation_tokens": cache_creation,
+            "cache_read_tokens": cache_read,
+            "cache_amortization": round(summary.cache_amortization, 4) if summary.cache_amortization_defined else None,
+            "stable_prefix_share": stable_prefix_share,
+            "volatile_prefix_share": volatile_prefix_share,
+            "volatile_tail_share": volatile_tail_share,
+            "max_prefix_position": max_prefix_position,
+            "max_prefix_position_volatile_share": max_prefix_position_volatile_share,
+            "dominant_transcript_share": dominant.get("share") if dominant else None,
+        },
+        "hypothesized_causes": hypothesized_causes,
+        "corroborated_causes": corroborated_causes,
+        "next_checks": next_checks,
+        "recommended_experiments": recommended_experiments,
+        "caveats": [
+            "Cache layout advice is a local transcript heuristic, not billing authority or provider-cache proof.",
+            "Observed issues come from cache fields and redacted segment statistics; causes remain hypotheses until corroborated by diet/structural evidence.",
+            "Generated command templates use placeholders and must not be treated as observed user commands or paths.",
+            "Use matched before/after audits before making token or cost savings claims.",
+        ],
+    }
+    summary.cache_layout_advice_cache = advice
+    return advice
+
+
+def cache_layout_advice_for_summary(summary: UsageSummary) -> dict[str, Any]:
+    return build_cache_layout_advice(summary)
+
+
 def build_metric_caveats(summary: UsageSummary) -> list[str]:
     caveats = [
         "Values are observed from local Claude Code transcript JSON/JSONL fields and are not official billing records.",
@@ -1433,6 +1651,7 @@ def feasibility_json(
     stable_total_tokens = sum(stable_tokens.values())
     cache_friendliness = cache_friendliness_for_summary(summary)
     cache_diagnostics = cache_diagnostics_for_summary(summary)
+    cache_layout_advice = cache_layout_advice_for_summary(summary)
     return {
         "schema_version": FEASIBILITY_SCHEMA_VERSION,
         "producer": FEASIBILITY_PRODUCER,
@@ -1452,6 +1671,7 @@ def feasibility_json(
                 "headroom_availability",
                 "cache_friendliness",
                 "cache_diagnostics",
+                "cache_layout_advice",
                 "totals",
             ],
             "diagnostic_fields": ["summary"],
@@ -1480,6 +1700,7 @@ def feasibility_json(
         "headroom_availability": availability["headroom"],
         "cache_friendliness": cache_friendliness,
         "cache_diagnostics": cache_diagnostics,
+        "cache_layout_advice": cache_layout_advice,
         "totals": {
             "total_tokens": stable_total_tokens,
             "tokens": stable_tokens,
@@ -1531,6 +1752,36 @@ def build_recommendations(summary: UsageSummary, top: int) -> list[dict[str, Any
     input_ratio = input_tokens / total
     cache_friendliness = cache_friendliness_for_summary(summary)
     cache_diagnostics = cache_diagnostics_for_summary(summary)
+    cache_layout_advice = cache_layout_advice_for_summary(summary)
+    if cache_layout_advice.get("observed_issue") == "volatile_prefix_breaker":
+        evidence = {
+            "observed_issue": cache_layout_advice.get("observed_issue"),
+            "priority": cache_layout_advice.get("priority"),
+            "confidence": cache_layout_advice.get("confidence"),
+            "cache_creation_tokens": cache_creation,
+            "cache_read_tokens": cache_read,
+        }
+        observed_summary = cache_layout_advice.get("observed_summary")
+        if isinstance(observed_summary, dict):
+            for key in ("max_prefix_position", "max_prefix_position_volatile_share", "stable_prefix_share", "volatile_prefix_share"):
+                evidence[key] = observed_summary.get(key)
+        rec = recommendation(
+            "prioritize-cache-prefix-stabilization",
+            "Prioritize cache-prefix stabilization before TTL or output trimming",
+            (
+                "Cache creation remains material and redacted segment statistics show a volatile early prefix; "
+                "this is an experiment-prioritization signal, not a confirmed root cause."
+            ),
+            (
+                "If one transcript dominates, split unrelated work into shorter sessions; then check startup/context "
+                "size and keep stable policy before volatile logs, diffs, timestamps, and generated evidence."
+            ),
+            str(cache_layout_advice.get("priority") or "P1"),
+            evidence,
+        )
+        rec["heuristic"] = True
+        rec["confidence"] = cache_layout_advice.get("confidence")
+        recs.append(rec)
     for finding in cache_friendliness.get("findings", []):
         if isinstance(finding, dict) and finding.get("id") == "volatile-content-near-prefix":
             evidence = dict(finding.get("evidence") or {})
@@ -1754,6 +2005,7 @@ def summary_json(
         "top_tools": counter_json(summary.by_tool, top),
         "cache_friendliness": cache_friendliness_for_summary(summary),
         "cache_diagnostics": cache_diagnostics_for_summary(summary),
+        "cache_layout_advice": cache_layout_advice_for_summary(summary),
     }
     if include_recommendations:
         data["recommendations"] = build_recommendations(summary, top)
@@ -1887,6 +2139,26 @@ def main() -> int:
     headroom = cache_diagnostics.get("headroom_diagnostics") or {}
     print(f"  headroom_status         {headroom.get('status')} ({headroom.get('evidence')})")
 
+    cache_layout_advice = cache_layout_advice_for_summary(summary)
+    if cache_layout_advice.get("status") != "missing" or cache_layout_advice.get("observed_issue") != "unknown":
+        print("\nCache layout advice")
+        print(f"  status                  {cache_layout_advice.get('status')}")
+        print(f"  confidence              {cache_layout_advice.get('confidence')}")
+        print(f"  observed_issue          {cache_layout_advice.get('observed_issue')}")
+        print(f"  priority                {cache_layout_advice.get('priority')}")
+        experiments = cache_layout_advice.get("recommended_experiments") or []
+        if experiments:
+            first = experiments[0]
+            print(f"  first_experiment        {first.get('id')} ({first.get('priority')})")
+            print(f"  experiment_action       {first.get('action')}")
+        checks = cache_layout_advice.get("next_checks") or []
+        if checks:
+            first = checks[0]
+            print(f"  next_check              {first.get('id')}")
+            templates = first.get("command_templates") or []
+            if templates:
+                print(f"  command_template        {templates[0]}")
+
     model_totals = Counter({model: sum(tokens.values()) for model, tokens in summary.by_model.items()})
     print_counter("By model", model_totals, args.top)