pi-smart-compact 7.20.0 → 7.22.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## [7.22.0] - 2026-07-15
+
+### Added
+- Independent `summaryThinkingLevel` and `segmentationThinkingLevel` settings control per-phase reasoning, including `max`, while preserving provider defaults when unset.
+
+## [7.21.0] - 2026-07-15
+
+### Fixed
+- Canonical summary parsing now recognizes canonical H3 headings, merges duplicate sections, and preserves H3-only summaries during state injection.
+- File verification uses collision-aware path needles; one monorepo basename can no longer satisfy multiple modified files.
+- Every deterministic verification gap is repaired regardless of scalar score; typed gaps and repair provenance replace string-prefix policy.
+- Recent-tail and batch planning count structured tool-call arguments with run-scoped provider/model calibration.
+- Access pruning deduplicates only identical tool name + argument signatures; read/search/list evidence no longer collapses by path alone.
+- MCP snake-case edit aliases are classified as mutations without treating ambiguous `path + text` payloads universally as writes.
+- Incremental extraction reconciles cached unresolved errors against successful retries in the new suffix.
+- LLM call counts now come from the run-scoped metrics sink, including probes, retries, failures and patches.
+
+### Added
+- High-confidence secret scrubbing at provider, extraction-cache, backup, state and pending-summary boundaries; optional PII scrubbing.
+- Optional fail-closed manual Apply/Cancel approval gate with verification provenance.
+- Exact max-call and max-latency budgets with deterministic degradation, plus `--focus` budget weighting.
+- Online `session_compact` → `message_end` damage monitoring and opt-in adaptive preservation policy.
+- `/smart-compact loops` manager for resolve/reopen, priority and pin/unpin overrides with stable summary identity across runs.
+- Deterministic adversarial EESV release gate (`bun run gate`) covering parser, verification, tools, cache, budgets, scrubbing and damage.
+
+### Changed
+- Public README redesigned for npm, GitHub and Pi package surfaces with install-first quick start, progressive EESV documentation, complete configuration, safety/privacy guidance and current recovery/observability flows.
+- Extraction and exploration share one deduplicated fact context; runtime call accounting now comes from the metrics sink instead of inferred round counts.
+- CI and the release checklist now run the adversarial EESV gate.
+
 ## [7.20.0] - 2026-07-14
 
 ### Fixed

package/README.md

@@ -1,37 +1,20 @@
 <div align="center">
 
-<img src="./docs/assets/banner.svg" alt="pi-smart-compact" width="860" />
+<a href="https://github.com/alpertarhan/pi-smart-compact">
+  <img src="https://raw.githubusercontent.com/alpertarhan/pi-smart-compact/main/docs/assets/banner.svg" alt="pi-smart-compact" width="860" />
+</a>
 
 [![CI](https://github.com/alpertarhan/pi-smart-compact/actions/workflows/ci.yml/badge.svg)](https://github.com/alpertarhan/pi-smart-compact/actions/workflows/ci.yml)
 [![npm version](https://img.shields.io/npm/v/pi-smart-compact?color=60a5fa)](https://www.npmjs.com/package/pi-smart-compact)
-[![license](https://img.shields.io/npm/l/pi-smart-compact?color=22c55e)](./LICENSE)
-[![Pi extension](https://img.shields.io/badge/Pi-extension-fbbf24)](https://github.com/earendil-works/pi)
+[![license](https://img.shields.io/npm/l/pi-smart-compact?color=22c55e)](https://github.com/alpertarhan/pi-smart-compact/blob/main/LICENSE)
+[![Pi package](https://img.shields.io/badge/Pi-package-fbbf24)](https://github.com/earendil-works/pi)
 
-**Verification-oriented smart compaction for the [Pi Coding Agent](https://github.com/earendil-works/pi-coding-agent).**
+### Verification-oriented context compaction for the Pi Coding Agent
 
-</div>
-
-Default compaction trims your conversation blind. `pi-smart-compact` keeps what
-the agent actually needs to continue — the **goal, changed files, unresolved
-errors, decisions, constraints, and open loops** — through a verified
-**Extract → Explore → Synthesize → Verify** pipeline.
-
-> Facts first, synthesis second, verification last.
-
----
-
-## Why
+Preserve the agent's **working state**—goals, files, decisions, errors,
+constraints, and open loops—not just a vague recap of the conversation.
 
-Default compaction produces a vague recap and quietly drops the operational
-context that matters most during coding. The result is the classic
-*"didn't we already fix this?"* loop.
-
-| Default compaction | `pi-smart-compact` |
-| --- | --- |
-| Trims by token count | Extracts facts deterministically (zero LLM) |
-| Generic prose recap | Structured working-state summary |
-| Loses files / errors / decisions | Preserves them, then **verifies** they survived |
-| No regression signal | Damage detection + metrics dashboard |
+</div>
 
 ## Install
 
@@ -39,7 +22,7 @@ context that matters most during coding. The result is the classic
 pi install npm:pi-smart-compact
 ```
 
-From GitHub:
+Or install directly from GitHub:
 
 ```bash
 pi install git:github.com/alpertarhan/pi-smart-compact
@@ -48,237 +31,354 @@ pi install git:github.com/alpertarhan/pi-smart-compact
 ## Quick start
 
 ```bash
-/smart-compact                              # interactive — pick model + profile
-/smart-compact anthropic/claude-sonnet-4 balanced
-/smart-compact "focus on auth + unresolved follow-ups"
-/smart-compact metrics                      # profile / provider comparison
-/smart-compact dashboard                    # interactive TUI dashboard
-/smart-compact restore                      # list + view + restore backups
+/smart-compact                                         # interactive model + profile picker
+/smart-compact balanced                                # direct profile
+/smart-compact anthropic/claude-sonnet-4 balanced     # direct model + profile
+/smart-compact balanced --focus=auth                   # preserve extra auth detail
+/smart-compact metrics                                 # text metrics report
+/smart-compact dashboard                               # interactive metrics dashboard
+/smart-compact restore                                 # browse and restore backups
+/smart-compact loops                                   # manage persisted open loops
 ```
 
-Or let the agent call it as a tool on long sessions:
+The extension also participates in Pi's native compaction flow automatically
+when actual context usage crosses the configured threshold (60% by default),
+and exposes a `smart_compact` tool for long-running agents.
 
-```jsonc
-{
-  "name": "smart_compact",
-  "parameters": { "profile": "balanced", "dashboard": false }
-}
+> The tool path stages a safe pending summary. It never compacts the active
+> conversation in the middle of an agent turn.
+
+## Why smart compaction?
+
+| Native-style recap | `pi-smart-compact` |
+| --- | --- |
+| Summarizes prose | Preserves operational coding state |
+| Trusts one LLM response | Extracts deterministic ground truth first |
+| File/error omissions can be silent | Verifies coverage and repairs known gaps |
+| One strategy for every session | Chooses single-pass or hierarchical synthesis |
+| No quality feedback | Tracks provenance, damage signals, and metrics |
+
+The design principle is simple:
+
+> **Facts first. Synthesis second. Verification before apply.**
+
+## EESV pipeline
+
+```text
+Pi conversation
+      │
+      ▼
+┌───────────┐   ┌───────────┐   ┌────────────┐   ┌───────────┐
+│  Extract  │ → │  Explore  │ → │ Synthesize │ → │  Verify   │
+│ 0 LLM     │   │ adaptive  │   │ 1-pass or  │   │ + repair  │
+│ calls     │   │           │   │ hierarchical│   │           │
+└───────────┘   └───────────┘   └────────────┘   └───────────┘
+                                                           │
+                                                           ▼
+                                               staged/applied by Pi
 ```
 
-Auto-compaction also runs before Pi's native compact once context pressure
-crosses your threshold (default 60% **actual** context usage).
+| Stage | Responsibility |
+| --- | --- |
+| **Extract** | Deterministically catalogs files, errors, decisions, constraints, topics, media metadata, and open loops. This is the verification ground truth. |
+| **Explore** | Uses a cheaper segmentation model when a complex session needs deeper topic boundaries or error-chain inspection. Simple sessions skip it. |
+| **Synthesize** | Uses one pass for short sessions and bounded chunk/assembly fallbacks for long sessions. Focus and call/latency budgets are enforced here. |
+| **Verify** | Checks canonical sections and extracted facts, applies every safe deterministic repair, and escalates only unresolved low-scoring gaps to an LLM patch. |
 
-## How it works
+### What survives compaction
 
-```mermaid
-flowchart LR
-    A["Extract<br/>deterministic facts<br/><i>0 LLM calls</i>"] --> B["Explore<br/>optional deep<br/>analysis"]
-    B --> C["Synthesize<br/>single-pass or<br/>chunked summary"]
-    C --> D["Verify<br/>score gaps,<br/>repair"]
-    D --> E["Return verified<br/>summary to Pi"]
-```
+- The current goal and user constraints
+- Modified, read, and deleted files
+- Unresolved **and** resolved error history
+- Explicit and implicit decisions
+- Open follow-ups, blockers, priorities, and pinned loops
+- Next actions and critical continuation context
+- Changes since the previous compaction
+
+Summaries use a canonical H1/H2/H3-aware structure, collision-safe file
+matching, typed verification gaps, and persisted repair provenance.
 
-| Stage | What it does |
+## Usage surfaces
+
+| Surface | Behavior |
 | --- | --- |
-| **Extract** | Deterministically pulls files, errors, decisions, constraints, topics, and open loops — no LLM, the ground truth. |
-| **Explore** | Optionally inspects the conversation more deeply when the session is complex. |
-| **Synthesize** | Single-pass for short sessions, Kamradt-style chunked + assembled for long ones. |
-| **Verify** | Scores the result against extracted facts and patches missing critical details. |
+| `/smart-compact` | Explicit manual run. Supports picker UI, direct args, dry-run, focus, and budgets. |
+| `session_before_compact` | Auto path. Runs before Pi's native compaction and returns a verification-scored result when context pressure is high. |
+| `smart_compact` tool | Agent path. Produces a pending summary for Pi's next natural compact; does not compact mid-turn. |
+| `/smart-compact loops` | Project-level open-loop manager: resolve/reopen, priority, pin/unpin. |
 
-**What it preserves:** user goal · constraints & preferences · modified / read /
-deleted files · unresolved & resolved errors · key decisions · open follow-up
-work · critical next-turn context · the delta since the previous compaction.
+### Focus and budgets
 
-## Integration surfaces
+```bash
+/smart-compact balanced --focus=authentication
+/smart-compact aggressive --max-calls=6 --max-latency=30000
+/smart-compact balanced --focus=src/auth.ts --max-calls=8
+```
 
-| Surface | When | Detail |
-| --- | --- | --- |
-| `/smart-compact` | Manual | Interactive picker or direct args; bypasses the adaptive gate. |
-| `session_before_compact` | Auto | Runs before Pi's native compaction when context pressure is high. |
-| `smart_compact` tool | Agent | Prepares a pending summary; Pi applies it on the next natural compact. |
+- `--focus` assigns more synthesis/exploration budget to a topic or path. It
+  does **not** attempt unsupported non-contiguous compaction.
+- `--max-calls` accepts `1–100`.
+- `--max-latency` accepts `5000–600000` milliseconds.
+- Call-budget exhaustion degrades to deterministic summaries. The latency
+  budget is a hard cancellation deadline.
 
-A short-lived pending summary is staged in memory (5-minute TTL) and handed to
-Pi when compaction is applied.
+The tool exposes equivalent `focus`, `max_calls`, and `max_latency_ms`
+parameters.
 
-## Example output
+## Profiles
 
-A generated summary follows a stable, structured contract:
+| Profile | Summary budget | Recent context kept | Best for |
+| --- | ---: | ---: | --- |
+| `light` | 10,000 tokens | 30,000 tokens | Maximum continuity and detail |
+| `balanced` | 6,000 tokens | 20,000 tokens | General use; default |
+| `aggressive` | 3,000 tokens | 10,000 tokens | Tight context budgets |
 
-```markdown
-## Goal
-Add retry/backoff to the LLM client so transient 429/5xx don't abort compaction.
+Profiles are a starting policy. Provider/model calibration, conversation shape,
+focus hints, damage feedback, and explicit budgets refine the actual run.
 
-## Constraints & Preferences
-- [requirement] never compact mid-turn from the tool path
+## Safety and privacy
 
-## Progress
-### Done
-- [x] Added `withRetry` wrapper in src/infra/llm-retry.ts
-### In Progress
-- [ ] Wire retry client into the services container
-### Blocked
-- None
+### Deterministic safeguards
 
-## Key Decisions
-- **Honor Retry-After verbatim**: providers that set it know their limits best.
+- Tool-call-aware recent-tail budgeting
+- Exact access-call pruning—different reads, searches, offsets, and patterns do not collapse
+- Tool-call/tool-result pair integrity at the compaction boundary
+- Collision-safe modified-file verification for monorepos
+- Mandatory deterministic repair for patchable verification gaps
+- Cross-session guard and five-minute TTL for pending summaries
+- Session-log recovery for older, truncated tool results
+- Retention-pruned backups before compaction
 
-## Files Modified
-- src/infra/llm-retry.ts
-- src/infra/llm-client.ts
+### Secrets and PII
 
-## Files Read
-- src/app/run-smart-compact.ts
+High-confidence secret scrubbing is enabled by default at every relevant trust
+boundary:
 
-## Open Loops
-- [high] Retried but unresolved: AbortSignal ignored by some providers
+```text
+provider request · extraction cache · backup · state · pending summary
+```
 
-## Changes Since Last Compaction
-- New files touched: src/infra/llm-retry.ts
-- New loops: AbortSignal ignored by some providers
+It covers common API keys, cloud/GitHub/Slack tokens, JWTs, bearer tokens,
+private keys, and credential assignments. Optional email/phone/payment-card
+scrubbing is available through `scrubPii`.
 
-## Next Steps
-1. Add an outer hard-timeout as a second line of defense
+Secret scrubbing is defense in depth, **not a replacement for proper secret
+handling or a dedicated DLP system**. See the
+[security policy](https://github.com/alpertarhan/pi-smart-compact/blob/main/SECURITY.md).
 
-## Critical Context
-- 408/425/429/5xx are retriable; 4xx (other) fails fast
+### Approval and feedback
+
+- `requireApproval: true` adds a fail-closed manual **Apply / Cancel** decision
+  after the provenance review screen. Auto and tool paths retain their native
+  staged lifecycle.
+- Online damage monitoring observes the first post-compaction messages and
+  records re-read files or repeated context. Remediation hints feed those files
+  into the next compaction.
+- `adaptiveDamageFeedback` can opt a project into larger preservation budgets
+  after repeated high-damage reports.
 
-## Topics Covered
-- LLM retry wrapper (high)
+## Open-loop control
+
+```bash
+/smart-compact loops
 ```
 
-A machine-readable `CompactionState` is built alongside it for reuse across
-later compactions (delta tracking, damage detection).
+The manager operates on the project's persisted `CompactionState`:
+
+- resolve or reopen a loop
+- change priority
+- pin or unpin it across later compactions
+
+Overrides use normalized summary identity instead of positional IDs, so a loop
+cannot accidentally inherit another loop's state on a later run.
 
 ## Configuration
 
-Add to `~/.pi/agent/settings.json`:
+Add `smartCompact` to `~/.pi/agent/settings.json`:
 
 ```json
 {
   "smartCompact": {
     "profile": "balanced",
-    "summaryModel": "anthropic/claude-sonnet-4",
+    "summaryModel": null,
+    "segmentationModel": null,
+    "summaryThinkingLevel": null,
+    "segmentationThinkingLevel": null,
     "autoTrigger": true,
     "minContextPercent": 60,
-    "backupEnabled": true
+    "backupEnabled": true,
+    "scrubSecrets": true,
+    "scrubPii": false,
+    "requireApproval": false,
+    "maxLlmCalls": 0,
+    "maxLatencyMs": 0,
+    "focusWeighting": true,
+    "onlineDamageMonitor": true,
+    "adaptiveDamageFeedback": false,
+    "pinPaths": []
   }
 }
 ```
 
-| Key | Type | Default |
-| --- | --- | --- |
-| `profile` | `light \| balanced \| aggressive` | `balanced` |
-| `summaryModel` | `string \| null` | `null` (uses session model) |
-| `segmentationModel` | `string \| null` | `null` |
-| `autoTrigger` | `boolean` | `true` |
-| `autoTriggerTimeoutMs` | `number` | `120000` |
-| `minContextPercent` | `number` | `60` |
-| `backupEnabled` | `boolean` | `true` |
-| `backupDir` | `string` | `~/.pi/agent/compact-backups` |
-| `profiles` | per-profile overrides | built-ins |
-| `pinPaths` | `string[]` | `[]` (paths always preserved) |
-
-### Profiles
-
-| Profile | Summary budget | Keep recent | Use when |
-| --- | ---: | ---: | --- |
-| `light` | 10000 | 30000 | preserve more detail |
-| `balanced` | 6000 | 20000 | default, general use |
-| `aggressive` | 3000 | 10000 | tighter summaries |
+### Per-phase reasoning
 
-The legacy config key `semanticCompact` is still accepted.
+Exploration can use a cheaper reasoning level while final synthesis and repair
+use a stronger one:
 
-## Safeguards
+```json
+{
+  "smartCompact": {
+    "segmentationThinkingLevel": "low",
+    "summaryThinkingLevel": "high"
+  }
+}
+```
 
-**Correctness**
+`segmentationThinkingLevel` applies to exploration; `summaryThinkingLevel`
+applies to synthesis, assembly, and repair. Supported values are `minimal`,
+`low`, `medium`, `high`, `xhigh`, and `max`. Leave either value as `null` to
+preserve the provider's existing behavior. An explicit call-level reasoning
+option takes precedence over these defaults.
+
+<details>
+<summary><strong>All configuration keys</strong></summary>
+
+| Key | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `profile` | `light \| balanced \| aggressive` | `balanced` | Default policy profile |
+| `summaryModel` | `string \| null` | `null` | Uses the active session model when null |
+| `segmentationModel` | `string \| null` | `null` | Optional cheaper model for Explore |
+| `summaryThinkingLevel` | `minimal \| low \| medium \| high \| xhigh \| max \| null` | `null` | Reasoning level for synthesis and repair; provider default when null |
+| `segmentationThinkingLevel` | `minimal \| low \| medium \| high \| xhigh \| max \| null` | `null` | Reasoning level for exploration; provider default when null |
+| `autoTrigger` | `boolean` | `true` | Participate in Pi's native compact hook |
+| `autoTriggerTimeoutMs` | `number` | `120000` | Hard timeout for automatic runs |
+| `minContextPercent` | `number` | `60` | Actual context usage gate |
+| `backupEnabled` | `boolean` | `true` | Write a pre-compaction backup |
+| `backupDir` | `string` | `~/.pi/agent/compact-backups` | Empty config value uses this path |
+| `profiles` | object | built-ins | Per-profile numeric overrides |
+| `pinPaths` | `string[]` | `[]` | Always preserve matching paths |
+| `requireApproval` | `boolean` | `false` | Manual UI only; cancel/error fails closed |
+| `scrubSecrets` | `boolean` | `true` | High-confidence credential redaction |
+| `scrubPii` | `boolean` | `false` | Email/phone/card-shaped redaction |
+| `maxLlmCalls` | integer `0–100` | `0` | `0` means unlimited |
+| `maxLatencyMs` | `0` or `5000–600000` | `0` | `0` means unlimited |
+| `focusWeighting` | `boolean` | `true` | Weight focused topics/paths higher |
+| `onlineDamageMonitor` | `boolean` | `true` | Observe post-compaction regression signals |
+| `adaptiveDamageFeedback` | `boolean` | `false` | Increase preservation after repeated damage |
+
+The legacy `semanticCompact` root key is still accepted for compatibility.
+
+</details>
+
+## Example summary
+
+<details>
+<summary><strong>Show canonical output</strong></summary>
 
-- Deterministic extraction before any synthesis
-- Verification scoring with deterministic patching **before** LLM patching
-- Hallucinated file-reference detection (SemVer-aware)
-- Open-loop injection + cross-compaction delta tracking
-- Pinned-path preservation (`pinPaths`) — a deterministic, LLM-free guarantee
-- Damage auto-remediation — re-read files feed forward and get re-preserved next compaction
+```markdown
+## Goal
+Add retry/backoff to the LLM client without breaking cancellation.
 
-**Safety**
+## Constraints & Preferences
+- [requirement] Never compact mid-turn from the tool path.
 
-- Conversation backups before compaction (retention-pruned), browsable + restorable via `/smart-compact restore`
-- `toolCall` / `toolResult` pair integrity at the compaction boundary
-- Cross-session leak guard on the pending summary
-- Session-log recovery that bypasses truncation of older tool results
+## Progress
+### Done
+- [x] Added `withRetry` in `src/infra/llm-retry.ts`.
+### In Progress
+- [ ] Wire the retry client into run-scoped services.
+### Blocked
+- None.
 
-**Observability**
+## Key Decisions
+- **Honor Retry-After verbatim**: provider limits are authoritative.
 
-- Metrics logging with profile / provider comparison
-- Post-compaction damage (regression) detection
-- Interactive TUI + HTML dashboards
+## Files Modified
+- src/infra/llm-retry.ts
+- src/infra/llm-client.ts
 
-## Usage notes
+## Open Loops
+- [high] Preserve AbortSignal behavior across providers.
 
-- Auto / tool compaction is skipped while context is small (below 60% actual usage).
-- Manual `/smart-compact` bypasses that gate — you asked for it.
-- `pi-toolkit`'s `tool=XX%` means tool-output ratio, **not** context fullness;
-  smart-compact uses actual `context=XX%`.
-- The tool path does **not** compact mid-turn (it stages a pending summary).
-- Exploration is adaptive and may be skipped for simple sessions.
+## Changes Since Last Compaction
+- New files touched: src/infra/llm-retry.ts
+
+## Next Steps
+1. Add an outer timeout as a second line of defense.
+
+## Critical Context
+- Retry 408/425/429/5xx; fail fast on other 4xx responses.
+```
 
-## Companions & compatibility
+</details>
 
-Pi core libraries are host-provided wildcard peers and are excluded from the
-published bundle. This keeps the extension independent from Pi's release cadence:
-the lockfile provides a reproducible development baseline, while daily CI runs
-the full suite against the latest Pi packages without changing the manifest.
+## Observability and recovery
 
-`pi-smart-compact` is designed to coexist with — and recommended alongside —
-[`pi-toolkit`](https://github.com/ersintarhan/pi-toolkit). pi-toolkit handles
-everyday context hygiene (anchors, pivots, status lines, old tool-output
-trimming); smart-compact handles high-pressure verified compaction. The
-integration protects recent pi-toolkit anchors and recovers original tool
-outputs from the session log.
+```bash
+/smart-compact metrics       # text report
+/smart-compact dashboard     # interactive TUI; can write a local HTML report
+/smart-compact restore       # browse, inspect, and restore backups
+```
 
-Because smart-compact sits close to Pi's compaction path, take extra care with
-extensions that also rewrite compaction hooks, branch history, entry IDs, tool
-output, or the compaction boundary. If you run another automatic compaction /
-context-rewriting extension, prefer a single `session_before_compact` owner
-unless hook order is explicitly coordinated.
+Metrics include method, profile, provider, phase timing, token/call estimates,
+verification quality, cache behavior, redactions, adaptation, fallbacks, and
+cancelled runs.
 
-## Runtime artifacts
+<details>
+<summary><strong>Runtime artifacts</strong></summary>
 
-The extension writes under `~/.pi/agent/`:
+All files live under `~/.pi/agent/`.
 
 | Path | Purpose |
 | --- | --- |
-| `settings.json` | configuration (read) |
-| `compact-backups/` | conversation backups (retention-pruned) |
-| `.cache/compact-extraction-<session>.json` | incremental extraction cache |
-| `.cache/compact-metrics.jsonl` | metrics log (tail-retained, 5 MiB cap) |
-| `.cache/smart-compact-report.html` | HTML dashboard |
-| `.cache/smart-compact/projects/<projectId>.json` | project fingerprint |
-| `.cache/smart-compact/states/<projectId>.json` | reusable compaction state |
-| `.cache/smart-compact/damage-reports.jsonl` | regression signals (tail-retained, 5 MiB cap) |
-| `.cache/smart-compact/remediation-<projectId>.json` | files to re-preserve after damage |
+| `settings.json` | Configuration (read only) |
+| `compact-backups/` | Retention-pruned conversation backups |
+| `.cache/compact-extraction-<session>.json` | Incremental extraction cache |
+| `.cache/compact-metrics.jsonl` | Tail-retained metrics log; 5 MiB cap |
+| `.cache/smart-compact-report.html` | Local HTML dashboard |
+| `.cache/smart-compact/projects/<projectId>.json` | Project fingerprint |
+| `.cache/smart-compact/states/<projectId>.json` | Compaction state and loop overrides |
+| `.cache/smart-compact/damage-reports.jsonl` | Damage reports; 5 MiB cap |
+| `.cache/smart-compact/remediation-<projectId>.json` | Files to preserve after damage |
+
+</details>
+
+## Compatibility
+
+Pi core packages are host-provided wildcard peers and are excluded from the
+published bundle. The lockfile gives contributors a reproducible baseline,
+while CI validates the latest Pi release daily without changing the manifest.
+An exact version can be checked with `bun run compat:pi <version>`.
+
+`pi-smart-compact` is designed to coexist with
+[`pi-toolkit`](https://github.com/ersintarhan/pi-toolkit): toolkit handles daily
+context hygiene; smart-compact handles high-pressure verified compaction. If
+another extension also owns `session_before_compact` or rewrites branch history,
+coordinate hook order or prefer a single automatic compaction owner.
 
 ## Development
 
 ```bash
 bun install
-bun run typecheck   # tsc --noEmit
-bun test            # full test suite
-bun run bench       # repeatable hot-path benchmark
-bun run compat:pi   # latest Pi, without changing package.json or bun.lock
-bun run compat:pi 0.80.6  # optional exact Pi version
-bun run build       # dist/ output for publishing
+bun run typecheck
+bun test
+bun run gate          # deterministic adversarial EESV release gate
+bun run bench
+bun run build
+bun run compat:pi     # isolated latest-Pi compatibility check
 ```
 
-Pull requests run the same verification in GitHub Actions before merge.
+Pull requests run typecheck, the complete test suite, the adversarial gate, and
+the build in GitHub Actions.
 
-## Documentation
+## Project documentation
 
-- [`ARCHITECTURE.md`](./ARCHITECTURE.md) — system design, execution model, layer responsibilities
-- [`CHANGELOG.md`](./CHANGELOG.md) — release history
-- [`CONTRIBUTING.md`](./CONTRIBUTING.md) — contributor workflow and expectations
-- [`SECURITY.md`](./SECURITY.md) — vulnerability reporting and data-handling notes
-- [`SUPPORT.md`](./SUPPORT.md) — where to ask for help
-- [`docs/RELEASE.md`](./docs/RELEASE.md) — release checklist
+- [Architecture](https://github.com/alpertarhan/pi-smart-compact/blob/main/ARCHITECTURE.md)
+- [Changelog](https://github.com/alpertarhan/pi-smart-compact/blob/main/CHANGELOG.md)
+- [Contributing](https://github.com/alpertarhan/pi-smart-compact/blob/main/CONTRIBUTING.md)
+- [Security](https://github.com/alpertarhan/pi-smart-compact/blob/main/SECURITY.md)
+- [Support](https://github.com/alpertarhan/pi-smart-compact/blob/main/SUPPORT.md)
+- [Release checklist](https://github.com/alpertarhan/pi-smart-compact/blob/main/docs/RELEASE.md)
 
 ## License
 

package/dist/app/run-context.d.ts

@@ -38,6 +38,7 @@ import type { CompressionProfile, LlmMessage, StructuredExtraction, ExplorationR
 import type { PendingSlot } from "./pending-slot.ts";
 import type { PruningResult } from "../utils/pruning.ts";
 import type { CompactionTier } from "../utils/helpers.ts";
+import type { TokenEstimator } from "../utils/tokens.ts";
 import type { SmartCompactServices } from "../infra/services.ts";
 export type Notifier = (msg: string, type?: "info" | "success" | "warning" | "error") => void;
 export interface CancellationToken {
@@ -76,6 +77,8 @@ export interface RcBase {
     isRunning: Cell<boolean>;
     flags: RunFlags;
     userNote?: string;
+    focus?: string;
+    maxLlmCalls?: number;
     timeoutMs: number;
     phaseTimings: PipelinePhaseTiming[];
     pipelineStart: number;
@@ -91,6 +94,8 @@ export interface PreparedExt {
     config: CompactConfig;
     profileCfg: ProfileConfig;
     providerCaps: ProviderCapabilities;
+    estimator: TokenEstimator;
+    adapted: boolean;
     summaryAuth: ResolvedAuth;
     segAuth: ResolvedAuth;
 }
@@ -157,6 +162,7 @@ export interface VerifiedExt extends SynthesizedExt {
     readonly _verified: true;
     verificationScore: number;
     verificationGaps: string[];
+    verificationProvenance: import("../types.ts").VerificationProvenance;
     verified: boolean;
 }
 export type VerifiedRc = RcBase & VerifiedExt;