ithrl 0.3.0__tar.gz → 0.4.0__tar.gz

{ithrl-0.3.0 → ithrl-0.4.0}/.gitignore

@@ -10,6 +10,7 @@ __pycache__/
 .coverage
 .coverage.*
 htmlcov/
+/.benchmarks/
 
 # Build artifacts
 build/

{ithrl-0.3.0 → ithrl-0.4.0}/CHANGELOG.md

@@ -1,5 +1,17 @@
 # CHANGELOG
 
+## v0.4.0 (2026-11-14)
+
+### Features
+
+- Inspect recorded operations across compaction ([#69](https://github.com/eberkut/ithrl/pull/69), [`3594d32`](https://github.com/eberkut/ithrl/commit/3594d3212b6dbc92276223f373908529e95a5e9e))
+- Prepare native reduction experiments offline ([#66](https://github.com/eberkut/ithrl/pull/66), [`13c9626`](https://github.com/eberkut/ithrl/commit/13c96260335982a3a3ce52ea9c73b327f649efce))
+- Qualify passive compaction inspection ([#70](https://github.com/eberkut/ithrl/pull/70), [`3b43a1b`](https://github.com/eberkut/ithrl/commit/3b43a1b8ef0c02bfd0182650460e4efed1c13076))
+
+### Performance Improvements
+
+- Reduce workflow overhead and track performance ([#71](https://github.com/eberkut/ithrl/pull/71), [`ae0c8cd`](https://github.com/eberkut/ithrl/commit/ae0c8cd238eff742ec51076a1054007580c9c0db))
+
 ## v0.3.0 (2026-11-10)
 
 ### Features

{ithrl-0.3.0 → ithrl-0.4.0}/CONTRIBUTING.md

@@ -72,19 +72,74 @@ Install the local hooks with `uv run pre-commit install`; run them on the whole
 `uv run pre-commit run --all-files`. Ruff and rumdl format files in place. CI checks formatting
 without modifying files.
 
-Recognized Markdown-only PRs skip Python linting, typing, unit-test matrices and dependency audits.
-They retain Markdown formatting/linting, documentation tests, the strict site build, workflow and
-dependency review, and all package build/install checks. Mixed changes, unknown paths, configuration
-changes and PRs with 3,000 or more changed files run full validation. Rename detection considers
-both paths; deletions participate. Failed path detection fails the required Workflows check.
-Main-branch, scheduled, manual and release runs always perform full validation.
-
-The required `Python tests` check summarizes the test matrix. It accepts a skipped matrix only
-after successful Markdown-only classification. Failed classification, missing decisions, test
-failures and unexpected skips fail this check.
+Markdown-only PRs skip Python linting, typing, unit tests and dependency audits. They still run
+Markdown, documentation, strict site, workflow, dependency-review and package checks. Mixed changes,
+unknown paths, configuration changes or 3,000 or more changed files require full validation;
+classification includes deleted files and both sides of renames. Failed detection fails Workflows.
+Main, scheduled, manual and release runs always validate fully. The required `Python tests` summary
+accepts a skipped matrix only after successful Markdown-only classification; missing decisions,
+failures and unexpected skips fail it.
 
 The logo sources, usage rules and regeneration commands are in [branding](docs/branding/README.md).
 
+## Performance and maintainability
+
+Measure the affected workflow before optimizing it. Keep sanitized input generation and setup
+outside timings; record the revision, locked environment, input size, repeats and noise. Measure
+allocations separately from elapsed time. Include index/cache construction and retained memory,
+then repeat the same workload after the change. Provider latency and local implementation overhead
+are separate measurements.
+
+- Choose collections for their operations: a set for repeated membership, a dictionary for keyed
+  lookup, and a sequence for authoritative order. For example, fuzz proposal membership can use a
+  local set while seeded traversal retains the original sequence. Measure scaling near admitted
+  limits as well as small inputs; Radon scores alone do not justify a refactor.
+- Keep reusable derived facts with the owner of their immutable inputs. Define copy/invalidation
+  behavior and memory bounds before adding a cache. A frozen model can still copy stale derived
+  state. Do not expose mutable internal indexes or borrow mutable native records across owners.
+- Bound both output and examined work. Count rejected and duplicate proposals where the work cap
+  requires it. Avoid repeated whole-input scans when the required operation is a keyed lookup.
+  Release large temporary buffers before processing the next item.
+- Batch fresh persistence reads where their consistency contract permits it. Preserve schema,
+  identity, chronology and corruption checks, locks, durable dispatch and accounting. Persisted
+  files and external state need fresh validation; an in-memory cache is not their authority. Reuse
+  validated facts within one synchronous operation; refresh after callbacks, waits or execution.
+- Test configurable limits with small inputs at the exact boundary and one beyond; assert policy
+  defaults separately when needed. Use sparse files for size-only filesystem checks. Share completed
+  immutable fixture data, not mutable cases or stores. Retain real process, SQLite and distribution
+  checks when they establish lifecycle, recovery or artifact behavior.
+- Share an existing mechanism only when its ownership, errors and side effects fit. Require a
+  concrete maintenance benefit from abstractions; keep different harness and statistical rules
+  explicit. Compare behavior, failure paths and recovery as well as performance.
+
+### Benchmarks
+
+The permanent [pytest-benchmark](https://pytest-benchmark.readthedocs.io/en/latest/) workloads
+live in `tests/benchmarks/`. They use sanitized inputs and no native harness or provider.
+Ordinary test runs skip them. From the repository root, save a baseline before changing code:
+
+```bash
+uv run pytest tests/benchmarks --benchmark-only --no-cov --benchmark-save=before
+```
+
+After the change, compare against that saved run:
+
+```bash
+uv run pytest tests/benchmarks --benchmark-only --no-cov --benchmark-compare=0001 --benchmark-save=after
+```
+
+Replace `0001` with the baseline ID printed by the first command. The plugin keeps saved runs
+under the ignored `.benchmarks/` directory. Compare identical workloads on the same interpreter
+and machine with low competing load. Check the distributions and memory tradeoffs; do not infer
+a regression from a small noisy difference. Keep setup outside the measured call and assert
+outcomes. Stateful workloads need equivalent starting state for every round.
+
+CI runs the benchmarks on Python 3.14 in the existing Quality job. Non-PR runs retain the generated
+JSON as `benchmarks-python-3.14` artifacts for 90 days. Download comparable runs and inspect them
+with `uv run pytest-benchmark compare FIRST.json SECOND.json`. There is no elapsed-time failure
+threshold; benchmark assertions still fail on incorrect behavior. Saved JSON contains machine and
+commit metadata; raw profiles and private-workflow inputs do not belong in these artifacts.
+
 ## Workflow and dependency checks
 
 For GitHub Actions or Dependabot changes, use the jactionlint release pinned in
@@ -106,14 +161,11 @@ uv export --locked --all-groups --all-extras --no-emit-project --format requirem
   uv run --locked --group audit pip-audit --strict --disable-pip --require-hashes -r /dev/stdin
 ```
 
-The hashed export is temporary pipeline input. The audit queries PyPI's vulnerability service for
-package names and versions without installing those packages, resolving alternatives or applying
-fixes. CI evaluates markers on each supported Python version. This covers locked versions rather
-than every version permitted by package dependency ranges.
-
-For dependency changes, run the lockfile audit above on each supported Python version. GitHub's
-dependency graph may omit packages from `uv.lock`, so Dependabot and Dependency Review cannot
-replace that audit.
+The audit sends locked package names and versions to PyPI's vulnerability service. It installs
+nothing, resolves no alternatives and applies no fixes. It covers locked versions, not entire
+dependency ranges. For dependency changes, run it on each supported Python version to evaluate
+markers. Dependabot and Dependency Review cannot replace it: GitHub's dependency graph may omit
+lockfile packages.
 
 The PR dependency-review job rejects newly introduced known vulnerabilities at any severity across
 runtime, development and unknown scopes. It uses a read-only token and does not check out or execute
@@ -138,13 +190,41 @@ Keep installation and first-use instructions in README, and detailed user guides
 `docs/`. Support, security and conduct policies live at the repository root. Keep private sessions,
 cases and credentials out of documentation and generated output.
 
-Use [Diátaxis](https://diataxis.fr/) to match a section to the reader's need. A tutorial guides
-learning through a reproducible example with expected results. A how-to gives prerequisites,
-actions and a success check for a specific task. Reference describes commands and contracts;
-explanation covers rationale, evidence and limits. Link between these when the reader needs more
-detail. Apply the distinction within existing pages; add a page when it has a separate purpose.
-Use concrete instructions and claims supported by evidence. Remove filler, promotional language
-and repeated explanations.
+### Writing and review
+
+Start with the reader's task. Use [Diátaxis](https://diataxis.fr/start-here/) to distinguish a
+guided learning example, a task-specific how-to, reference facts and explanation. A README can
+combine orientation and first use; do not split pages just to fill those categories.
+
+- Put prerequisites before commands, conditions before dependent actions and the expected result
+  after a step that needs verification. Use numbered steps for a sequence and tables for
+  comparisons.
+- State what the reader can do or conclude. Prefer concrete verbs and established terms; remove
+  filler, promotional claims, rhetorical contrasts and sentences that repeat their heading.
+  For example, replace “It is important to note that execution requires explicit acknowledgement”
+  with “After reviewing the plan, pass `--acknowledge-model-execution` to allow provider calls.”
+- Give each topic one owner. Keep options in the generated CLI reference, procedures in user guides,
+  measurements in `docs/measurements.md`, rationale in decisions and methods in research. Link to
+  detail instead of repeating it. Keep essential safety conditions beside the affected action.
+- Shorten without widening claims. Preserve tested profiles, statistical conditions, costs,
+  uncertainty, failed outcomes and historical context. “The screen passed” does not mean
+  “preservation is confirmed.” Check commands against the current CLI and qualify future work.
+- Follow [W3C's writing guidance](https://www.w3.org/WAI/tips/writing/): use descriptive link text,
+  ordered headings and useful image alternatives. Do not rely on color alone. Keep code blocks
+  executable or identify placeholders before the command.
+
+Before review, check: can the intended reader find the task, run its steps and interpret the
+result? Does each paragraph add information? Are terms, claims, links and generated content current?
+Check the [documentation commands](#building-and-checking-documentation) below after edits.
+
+For additional guidance, consult the
+[Google developer documentation style guide](https://developers.google.com/style) and
+[Microsoft Writing Style Guide](https://learn.microsoft.com/en-us/style-guide/welcome/).
+Follow this project's conventions where they differ.
+Use judgment rather than word-count targets; explanations and research need enough detail to support
+their conclusions.
+
+### Documentation ownership
 
 [ROADMAP.md](ROADMAP.md) describes future direction. GitHub issues own actionable scope,
 dependencies, acceptance criteria and status; release milestones group scope and the public
@@ -162,12 +242,12 @@ Before evaluating a new study, declare its tested domain, criteria, seeds, budge
 claims. Report costs across complete workflows, including failed and incomplete work, and document
 the alternatives and limitations needed to interpret the results.
 
-The optional `docs` dependency group pins MkDocs and the shadcn theme. Search runs in the browser;
-fonts and scripts are served with the site. GitHub star-count requests and raw Markdown copying
-are disabled. A local hook admits only the packaged theme assets used by this configuration.
-When changing the theme or enabled extensions, check that asset list and the
-[third-party notices](docs/third-party-notices.txt) alongside the rendered site.
-To preview the site locally:
+### Building and checking documentation
+
+The `docs` group pins MkDocs and the shadcn theme. Search runs in the browser; the site bundles
+fonts and scripts. GitHub star-count requests and raw Markdown copying are disabled. When changing
+the theme or extensions, review the asset allowlist in `scripts/docs_theme.py`, the
+[third-party notices](docs/third-party-notices.txt) and the rendered site. To preview:
 
 ```bash
 uv sync --locked --all-groups --all-extras
@@ -303,10 +383,8 @@ CodeRabbit's optional planning and code-generation features are configured in
 
 ## Preparing a release
 
-The release procedures below are for maintainers with repository and package-publishing access.
-
-For every feature, aim for parity across supported harnesses. Any exception must be clearly
-justified and documented before release.
+Maintainers need repository and package-publishing access. Before release, justify and document
+any feature-parity exception between supported harnesses.
 
 Python Semantic Release, pinned in the `release` dependency group, calculates versions from
 Conventional Commits. `pyproject.toml` is the version source; installed CLI and Codex client
@@ -315,9 +393,8 @@ history, omitting routine build, CI, documentation, style and test commits. Its
 [template](.github/changelog/CHANGELOG.md.j2) keeps lists compact, with one entry per source line.
 Change the template to adjust formatting; do not edit generated entries by hand.
 
-A maintainer starts preparation; Semantic Release chooses the version and writes the notes.
-Review and merge the generated files through a PR so CI tests the prepared version before the
-publication workflow builds it. The publication workflow uses that committed version.
+Review and merge generated version/notes changes through a PR. CI tests the prepared version;
+publication builds that committed version.
 
 Use `main` with complete history and all existing release tags available. Preview the next version
 without changing files, the index, commits, tags or remote state:
@@ -402,11 +479,11 @@ gh workflow run release.yml --repo eberkut/ithrl --ref main \
 6. Verify the published versions, hashes, attestations and installed example. A successful upload
    alone does not complete release acceptance.
 
-Complete review within 30 days: release artifacts are retained for 30 days, and GitHub limits the
-total workflow lifetime, including approval waits. Start only one release at a time; concurrency
-preserves the active run but GitHub may replace an older pending run when another is queued.
-Do not rerun the whole workflow to promote a completed rehearsal or cancel a run during upload.
-For failure or partial publication, inspect the index and existing release first; preserve the
-original files and hashes. Any recovery upload needs explicit approval and must use identical
-missing files. Never rebuild and overwrite a published version or suppress conflicts with
-`skip-existing`.
+Complete review within the 30-day artifact retention and GitHub workflow lifetime, including
+approval waits. Start one release at a time: a new queued run may replace an older pending run,
+though the active run is preserved. Do not rerun the workflow to promote a completed rehearsal or
+cancel during upload.
+
+After failure or partial publication, inspect the index and release before recovery. Preserve
+the original files and hashes; uploading identical missing files requires explicit approval.
+Never overwrite a published version with rebuilt files or suppress conflicts with `skip-existing`.

{ithrl-0.3.0 → ithrl-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: ithrl
-Version: 0.3.0
+Version: 0.4.0
 Summary: Find smaller agent contexts that preserve a selected model behavior
 Project-URL: Source, https://github.com/eberkut/ithrl
 Project-URL: Issues, https://github.com/eberkut/ithrl/issues
@@ -95,7 +95,15 @@ Use a new directory to repeat the example; extraction refuses to overwrite an ex
 ## Commands
 
 - `ithrl extract` browses saved sessions and creates a case from a selected decision.
+- `ithrl prepare CASE` generates a private reduction configuration from a preflight receipt and
+  statistical settings. Follow the
+  [preparation procedure](https://github.com/eberkut/ithrl/blob/main/docs/reduction.md).
 - `ithrl shrink CASE` searches for context removals that preserve the selected behavior.
+- `ithrl inspect sections CASE` lists editable text fields and paragraph boundaries without
+  displaying text or requiring a reduction result.
+- `ithrl inspect reacquire SESSION` compares recorded operations and captured results across
+  compaction. See
+  [passive inspection](https://github.com/eberkut/ithrl/blob/main/docs/results.md#inspect-recorded-compaction).
 - `ithrl inspect retained CASE --result RESULT` explains retained units and recorded removal trials
   from a saved reduction without model access. See
   [results and privacy](https://github.com/eberkut/ithrl/blob/main/docs/results.md#inspect-retained-context).
@@ -115,33 +123,40 @@ Returned actions are observed and denied. Cases contain copied session content;
 
 ## Supported inputs
 
-| Input | Extracted decisions | Reduction | Fuzzing |
-| --- | --- | --- | --- |
-| Bundled synthetic example | Synthetic tool request | Deterministic local runner | Local fake runner |
-| Codex CLI rollouts | Final responses | Experimental native runner; [paragraph-removal measurements](https://github.com/eberkut/ithrl/blob/main/docs/measurements.md#ordinary-session-paragraph-removal) | Experimental prior-user text appends |
-| Copilot CLI session events | Final responses and shell requests | Experimental final-response paragraph removal and denied `bash` runner | Experimental prior-user text appends for final-response targets |
-
-Native Codex and Copilot final-response fuzzing supports appending text to eligible prior user
-input while preserving the fixed triggering input. The
-[fuzzing walkthrough](https://github.com/eberkut/ithrl/blob/main/docs/native-runs.md#context-fuzzing)
-starts with a local example and covers native execution.
-
-[Saved-session measurements](https://github.com/eberkut/ithrl/blob/main/docs/measurements.md#saved-session-experiments)
-include ordinary Codex and Copilot final-response experiments that removed paragraphs from retained
-prior-user text and passed fresh confirmation at a 20-percentage-point preservation margin. The
+| Input | Extracted decisions | Reduction | Fuzzing | Passive inspection |
+| --- | --- | --- | --- | --- |
+| Bundled synthetic example | Synthetic tool request | Deterministic local runner | Local fake runner | — |
+| Codex CLI rollouts | Final responses | Experimental native runner; [paragraph-removal measurements](https://github.com/eberkut/ithrl/blob/main/docs/measurements.md#ordinary-session-paragraph-removal) | Experimental prior-user text appends | Exact recorded-operation and captured-result comparisons across compaction |
+| Copilot CLI session events | Final responses and shell requests | Experimental final-response paragraph removal and denied `bash` runner | Experimental prior-user text appends for final-response targets | Exact recorded-operation and captured-result comparisons across compaction |
+
+Passive inspection reads saved evidence without a harness or model access. The
+[worked investigation](https://github.com/eberkut/ithrl/blob/main/docs/research/passive-compaction-investigation.md)
+records the qualified native profiles, ordinary examples and interpretation limits.
+
+Native fuzzing appends text to eligible prior user input while preserving the fixed triggering
+input. The
+[fuzzing walkthrough](https://github.com/eberkut/ithrl/blob/main/docs/fuzzing.md)
+covers a local example and native execution.
+
+Ordinary Codex and Copilot paragraph-removal experiments passed fresh confirmation at a
+20-percentage-point preservation margin. See the
+[measurements](https://github.com/eberkut/ithrl/blob/main/docs/measurements.md#saved-session-experiments)
+for completed and unsuccessful outcomes, costs and qualification limits, and the
 [worked investigation](https://github.com/eberkut/ithrl/blob/main/docs/research/ordinary-session-investigation.md)
-explains what the smaller Codex context helped a developer inspect and what remains unresolved.
-The measurements distinguish private runtime qualification from integrated support and report
-resource usage and unsuccessful outcomes alongside completed runs. Check
+for a developer's interpretation. Check
 [native compatibility](https://github.com/eberkut/ithrl/blob/main/docs/native-runs.md#compatibility-and-measurements)
-for the installed harness's requirements.
+before using an installed harness.
 
 ## Documentation
 
 Read the [documentation site](https://eberkut.github.io/ithrl/) or browse the guides below.
 
 - [Native runs](https://github.com/eberkut/ithrl/blob/main/docs/native-runs.md): session selection,
-  experiment configuration, preflight, model execution and measured resource usage.
+  shared prerequisites and compatibility.
+- [Native reduction](https://github.com/eberkut/ithrl/blob/main/docs/reduction.md): prepare,
+  inspect and execute a context-removal experiment.
+- [Context fuzzing](https://github.com/eberkut/ithrl/blob/main/docs/fuzzing.md): try the local
+  example and run a native text-append campaign.
 - [Results and privacy](https://github.com/eberkut/ithrl/blob/main/docs/results.md): saved files,
   result interpretation, budgets, resume and sensitive data.
 - [Contributing](https://github.com/eberkut/ithrl/blob/main/CONTRIBUTING.md): issue-first

{ithrl-0.3.0 → ithrl-0.4.0}/README.md

@@ -62,7 +62,15 @@ Use a new directory to repeat the example; extraction refuses to overwrite an ex
 ## Commands
 
 - `ithrl extract` browses saved sessions and creates a case from a selected decision.
+- `ithrl prepare CASE` generates a private reduction configuration from a preflight receipt and
+  statistical settings. Follow the
+  [preparation procedure](https://github.com/eberkut/ithrl/blob/main/docs/reduction.md).
 - `ithrl shrink CASE` searches for context removals that preserve the selected behavior.
+- `ithrl inspect sections CASE` lists editable text fields and paragraph boundaries without
+  displaying text or requiring a reduction result.
+- `ithrl inspect reacquire SESSION` compares recorded operations and captured results across
+  compaction. See
+  [passive inspection](https://github.com/eberkut/ithrl/blob/main/docs/results.md#inspect-recorded-compaction).
 - `ithrl inspect retained CASE --result RESULT` explains retained units and recorded removal trials
   from a saved reduction without model access. See
   [results and privacy](https://github.com/eberkut/ithrl/blob/main/docs/results.md#inspect-retained-context).
@@ -82,33 +90,40 @@ Returned actions are observed and denied. Cases contain copied session content;
 
 ## Supported inputs
 
-| Input | Extracted decisions | Reduction | Fuzzing |
-| --- | --- | --- | --- |
-| Bundled synthetic example | Synthetic tool request | Deterministic local runner | Local fake runner |
-| Codex CLI rollouts | Final responses | Experimental native runner; [paragraph-removal measurements](https://github.com/eberkut/ithrl/blob/main/docs/measurements.md#ordinary-session-paragraph-removal) | Experimental prior-user text appends |
-| Copilot CLI session events | Final responses and shell requests | Experimental final-response paragraph removal and denied `bash` runner | Experimental prior-user text appends for final-response targets |
-
-Native Codex and Copilot final-response fuzzing supports appending text to eligible prior user
-input while preserving the fixed triggering input. The
-[fuzzing walkthrough](https://github.com/eberkut/ithrl/blob/main/docs/native-runs.md#context-fuzzing)
-starts with a local example and covers native execution.
-
-[Saved-session measurements](https://github.com/eberkut/ithrl/blob/main/docs/measurements.md#saved-session-experiments)
-include ordinary Codex and Copilot final-response experiments that removed paragraphs from retained
-prior-user text and passed fresh confirmation at a 20-percentage-point preservation margin. The
+| Input | Extracted decisions | Reduction | Fuzzing | Passive inspection |
+| --- | --- | --- | --- | --- |
+| Bundled synthetic example | Synthetic tool request | Deterministic local runner | Local fake runner | — |
+| Codex CLI rollouts | Final responses | Experimental native runner; [paragraph-removal measurements](https://github.com/eberkut/ithrl/blob/main/docs/measurements.md#ordinary-session-paragraph-removal) | Experimental prior-user text appends | Exact recorded-operation and captured-result comparisons across compaction |
+| Copilot CLI session events | Final responses and shell requests | Experimental final-response paragraph removal and denied `bash` runner | Experimental prior-user text appends for final-response targets | Exact recorded-operation and captured-result comparisons across compaction |
+
+Passive inspection reads saved evidence without a harness or model access. The
+[worked investigation](https://github.com/eberkut/ithrl/blob/main/docs/research/passive-compaction-investigation.md)
+records the qualified native profiles, ordinary examples and interpretation limits.
+
+Native fuzzing appends text to eligible prior user input while preserving the fixed triggering
+input. The
+[fuzzing walkthrough](https://github.com/eberkut/ithrl/blob/main/docs/fuzzing.md)
+covers a local example and native execution.
+
+Ordinary Codex and Copilot paragraph-removal experiments passed fresh confirmation at a
+20-percentage-point preservation margin. See the
+[measurements](https://github.com/eberkut/ithrl/blob/main/docs/measurements.md#saved-session-experiments)
+for completed and unsuccessful outcomes, costs and qualification limits, and the
 [worked investigation](https://github.com/eberkut/ithrl/blob/main/docs/research/ordinary-session-investigation.md)
-explains what the smaller Codex context helped a developer inspect and what remains unresolved.
-The measurements distinguish private runtime qualification from integrated support and report
-resource usage and unsuccessful outcomes alongside completed runs. Check
+for a developer's interpretation. Check
 [native compatibility](https://github.com/eberkut/ithrl/blob/main/docs/native-runs.md#compatibility-and-measurements)
-for the installed harness's requirements.
+before using an installed harness.
 
 ## Documentation
 
 Read the [documentation site](https://eberkut.github.io/ithrl/) or browse the guides below.
 
 - [Native runs](https://github.com/eberkut/ithrl/blob/main/docs/native-runs.md): session selection,
-  experiment configuration, preflight, model execution and measured resource usage.
+  shared prerequisites and compatibility.
+- [Native reduction](https://github.com/eberkut/ithrl/blob/main/docs/reduction.md): prepare,
+  inspect and execute a context-removal experiment.
+- [Context fuzzing](https://github.com/eberkut/ithrl/blob/main/docs/fuzzing.md): try the local
+  example and run a native text-append campaign.
 - [Results and privacy](https://github.com/eberkut/ithrl/blob/main/docs/results.md): saved files,
   result interpretation, budgets, resume and sensitive data.
 - [Contributing](https://github.com/eberkut/ithrl/blob/main/CONTRIBUTING.md): issue-first

ithrl-0.4.0/ROADMAP.md

@@ -0,0 +1,204 @@
+# Roadmap
+
+`ithrl` tests which context preserves a selected agent decision and which changes alter it.
+Development priorities depend on useful results, reliable measurement and measured execution cost.
+
+The [supported-inputs table](README.md#supported-inputs) describes current public capabilities.
+The roadmap records completed work and future direction. Future version labels establish an
+intended sequence, with scope and release dates decided from evidence.
+
+## Harness priorities
+
+Codex and GitHub Copilot are the primary harness integrations. Closing feature gaps between them
+is the current priority.
+
+## Completed: v0.2 context fuzzing
+
+The `ithrl fuzz` command explores bounded context changes, simplifies interventions and freshly
+confirms **at most one finding per campaign**: a declared decrease in the target's match probability
+among valid observations. This is conditional experimental evidence, not proof of a model defect,
+unique cause or semantic equivalence.
+
+Codex and Copilot prior-user append workflows have completed synthetic qualification. Their
+[measurements](docs/measurements.md#native-context-fuzzing) cover workloads, results and costs;
+[fuzzing research](docs/research/context-fuzzing.md) owns the method and assumptions.
+[Practical settings](https://github.com/eberkut/ithrl/issues/10) and
+[Copilot qualification](https://github.com/eberkut/ithrl/issues/29) record acceptance evidence.
+
+See the [fuzzing capability issue](https://github.com/eberkut/ithrl/issues/5) and
+[`v0.2.0` milestone](https://github.com/eberkut/ithrl/milestone/1) for scope and acceptance
+criteria.
+
+[Version 0.2.0](https://github.com/eberkut/ithrl/releases/tag/v0.2.0) is published, with
+[release preparation and publication](https://github.com/eberkut/ithrl/issues/11) complete.
+Broader mutation families and multiple-finding campaigns need their own evidence and prospective
+error allocation.
+
+## Completed: v0.3 deeper reduction
+
+Provider-free retained-context inspection and finer removal within supported prior-user text are
+implemented, with Codex and Copilot final-response workflows. Ordinary saved-session qualification
+and a [worked investigation](docs/research/ordinary-session-investigation.md) are complete; the
+[measurements](docs/measurements.md#ordinary-session-paragraph-removal) record outcomes, costs and
+limits. [Version 0.3.0](https://github.com/eberkut/ithrl/releases/tag/v0.3.0) is published.
+[Issue #12](https://github.com/eberkut/ithrl/issues/12) records the milestone's scope, acceptance
+and release evidence.
+
+Ablation, alternative reproducers, interaction analysis and statistically confirmed single-removal
+minimality remain deferred beyond v0.3.
+
+## Awaiting release: v0.4 preparation and passive compaction inspection
+
+[Experiment preparation](https://github.com/eberkut/ithrl/issues/48) is implemented in
+[PR #66](https://github.com/eberkut/ithrl/pull/66), keeping statistical choices, source identities
+and execution limits explicit. It is merged on main and awaits release in
+[v0.4.0](https://github.com/eberkut/ithrl/milestone/3).
+
+Passive compaction inspection for ordinary Codex and Copilot evidence is implemented under #15,
+with implementation in #64 and qualification in #65. Its
+[provider-free feasibility assessment](https://github.com/eberkut/ithrl/issues/15#issuecomment-6782516915)
+led to the current scope. The command has completed
+[ordinary-session qualification](docs/research/passive-compaction-investigation.md) through the
+CLI and both installed-artifact origins. It reports repeated recorded
+operations and equal or changed captured results without inferring avoidable work, causal effects or
+savings.
+
+The project-wide documentation review is complete in
+[PR #72](https://github.com/eberkut/ithrl/pull/72). All assigned v0.4 issues are complete on main;
+release preparation and publication remain. The investigations below have no release assignment and
+do not expand v0.4 scope.
+
+| Scope | Issue | Expected outcome |
+| --- | --- | --- |
+| Completed on main; awaiting v0.4 | [#48: experiment preparation](https://github.com/eberkut/ithrl/issues/48) | Generate and inspect private native reduction configurations without copying target/oracle blocks or digests by hand |
+| Completed on main; awaiting v0.4 | [#15: passive compaction inspection](https://github.com/eberkut/ithrl/issues/15) | Useful provider-free reports for both harnesses, with explicit operation/result relations and interpretation limits |
+| Completed on main; awaiting v0.4 | [#64: implement passive inspection](https://github.com/eberkut/ithrl/issues/64) | Bounded source projections, matching/report contracts and `inspect reacquire`; experimental reconstruction support is unchanged |
+| Qualification complete; awaiting v0.4 | [#65: qualify passive inspection](https://github.com/eberkut/ithrl/issues/65) | Ordinary sources, counterexamples and both installed-artifact origins validated; worked interpretation recorded |
+| Completed on main; awaiting v0.4 | [#67: performance and simplification](https://github.com/eberkut/ithrl/issues/67) | Project-wide performance fixes, permanent local-workload benchmarks and durable coding guidance, merged in [PR #71](https://github.com/eberkut/ithrl/pull/71) |
+| Completed on main; awaiting v0.4 | [#68: documentation and writing guidance](https://github.com/eberkut/ithrl/issues/68) | Project-wide documentation corrections and concise writing guidance, merged in [PR #72](https://github.com/eberkut/ithrl/pull/72) |
+| Research; no release assigned | [#16: broader workloads and costs](https://github.com/eberkut/ithrl/issues/16) | Measure source eligibility, useful developer conclusions, reliability and full costs, including unsuccessful sources and runs |
+| Candidate; no release assigned | [#13: comparative debugging](https://github.com/eberkut/ithrl/issues/13) | A comparability contract, paired workloads, interaction example and bounded validation proposal; decide whether to implement or defer |
+| Candidate; no release assigned | [#73: sampled inspection metadata](https://github.com/eberkut/ithrl/issues/73) | Persist reconstruction and policy metadata bound to plan identity for offline reports, distinguishing declarations from recorded attempt evidence |
+| Assessment; no release assigned | [#74: tool-output interventions](https://github.com/eberkut/ithrl/issues/74) | Assess native output visibility, source bindings and a useful localized intervention before proposing a new edit domain |
+| Deferred; no release assigned | [#14: additional harnesses](https://github.com/eberkut/ithrl/issues/14) | Assess Claude Code, OpenCode and Pi before choosing an integration order and qualification scope |
+| Deferred; no release assigned | [#18: portable archives and privacy](https://github.com/eberkut/ithrl/issues/18) | Define a useful sharing workflow, archive format and deliberate privacy review before implementation |
+| Research; no release assigned | [#17: baseline sharing](https://github.com/eberkut/ithrl/issues/17) | Reconsider reuse only if useful complete-workflow savings justify the statistical and recovery complexity |
+| Deferred research; no release assigned | [#61: ablation](https://github.com/eberkut/ithrl/issues/61) | Define retained-reproducer and full-original ablation, with distinct baselines and justified claims |
+| Deferred research; no release assigned | [#62: alternative reproducers and interactions](https://github.com/eberkut/ithrl/issues/62) | Assess useful differences between preserving contexts, redundancy and joint effects, with bounded discovery and confirmation |
+| Deferred research; no release assigned | [#63: confirmed single-removal minimality](https://github.com/eberkut/ithrl/issues/63) | Define the neighbor family, statistical claim, error allocation and complete comparison budget |
+
+## Next investigations
+
+Start with #16's provider-free workload preparation for both harnesses. Freeze debugging questions
+and selection criteria before choosing successful examples; retain exclusions and unsuccessful
+investigations.
+[ctx](https://github.com/ctxrs/ctx/blob/33ba4645b620fd89d138c6db1fabf33096a0ee16/docs/search.md) may
+help locate sessions, but ithrl must independently snapshot and validate native evidence. Measure
+useful developer conclusions alongside reduction, reliability and cost.
+
+Use the initial cohort to inform #13's good/bad-case comparison design and #74's tool-output
+assessment; neither must wait for the entire study. #74 must distinguish original output,
+delivered representation and saved evidence before proposing edits. #73's reporting improvement
+is independent. Execution and release scope remain separate decisions in the owning issues.
+
+The review of
+[SkillOpt's training method](https://github.com/microsoft/SkillOpt/blob/45f65ca04f5f6713bca7b9797b495696ba812751/docs/guide/training-loop.md)
+and
+[Sift's tool-output benchmarks](https://github.com/ctxrs/sift/blob/c22fb1b3747352dba8f8323c057d60e7afd92bf5/benchmarks/results/2026-09-21-release-v0.4.0/README.md)
+motivated better candidate selection and tool-output investigation. Their task-performance and
+output-size results do not establish ithrl's debugging usefulness. No search engine or skill
+optimizer is planned. Fuzzing already accepts supplied `stale_text`; #16 should establish a need for
+distinct proposals tied to specific fields before creating further work. Passive inspection retains
+its qualified exact-comparison contract; decoded or normalized matching needs a separate policy.
+
+## Release history and current scope
+
+### Deeper reduction
+
+Reduction within a message must preserve its native structure and protocol dependencies. Retained
+context inspection should distinguish protected or frozen material, dependency constraints,
+rejected removal trials, incomplete evidence and untested work. Trial explanations must identify
+the tested context; a rejected sampled screen does not establish behavioral necessity.
+
+[Ablation](https://github.com/eberkut/ithrl/issues/61) of a retained reproducer and of the full
+original answers different questions and must report its baseline.
+[Alternative reproducer and interaction research](https://github.com/eberkut/ithrl/issues/62) can
+expose several preserving contexts and joint effects; none is automatically a unique explanation.
+Deterministic single-removal minimality and
+[statistically confirmed minimality](https://github.com/eberkut/ithrl/issues/63) are distinct
+claims. The latter requires additional complete comparisons, error allocation and a budget that
+covers all advertised checks.
+
+### Comparative debugging and another integration
+
+`compare GOOD_CASE BAD_CASE` should search supported context differences with dependency-valid
+interventions. It must establish comparability of target, oracle, model/provider, request surface,
+environment and effective runner policy before attributing a regression to context. Differences in
+model, harness or execution environment remain explicit experimental factors.
+
+Claude Code, OpenCode and Pi are planned additional integrations. Claude Code and OpenCode have
+promising portability evidence in the [feasibility study](docs/research/feasibility.md); Pi needs an
+initial applicability assessment. Each requires an adapter, faithful reconstruction, isolation,
+calibration and a useful live workflow before becoming supported. Their order and release scope
+remain open; [the integration issue](https://github.com/eberkut/ithrl/issues/14) tracks assessment,
+prioritization and implementation. Add them incrementally while maintaining Codex and Copilot
+parity.
+
+### Passive reacquisition analysis
+
+The `inspect reacquire` implementation compares recorded operations and captured results
+across explicit compaction boundaries in one saved Codex or Copilot session. It starts with exact
+comparisons, keeps content and display scopes separate, and reports unknown state and completeness.
+Default output excludes private paths, arguments and text; detail requires bounded opt-in. It
+starts no harness, opens no referenced resources and makes no provider calls.
+
+Resume, fork, handoff and cross-harness matching remain later directions. Any normalized or
+heuristic matcher needs its own policy and qualification. Repeated operations or equal captured
+text do not prove avoidable retrieval, forgetting or effects caused by compaction. Passive
+inspection leaves active Codex compaction reconstruction unsupported; implementing agent handoffs
+is separate work.
+
+## Further capability candidates
+
+- Further mutation operations: supported whitespace changes, independent reordering and adding
+  stale or irrelevant observations outside prior-user text. State whether each tests expected
+  invariance or introduces intentional stress; a mutator name cannot prove semantic equivalence.
+- Optional `record` adapters for future sessions when ordinary saved evidence is insufficient.
+  Prior instrumentation must remain unnecessary for supported post-hoc extraction.
+- Trajectory runners where faithful execution seams and safe action policies exist. The current
+  single-decision experiment does not claim to reproduce a complete agent trajectory.
+- Custom command/Python runners and additional provider integrations with the same observation,
+  safety, identity and accounting contracts.
+- [Portable export/import and deliberate redaction](https://github.com/eberkut/ithrl/issues/18).
+  Exported experiments must state
+  external state requirements and omitted sensitive evidence; portable evidence does not require
+  a universal agent-session format.
+- Optional editor/agent integrations and handoff analysis that compose the CLI rather than
+  introducing separate experimental semantics.
+
+These candidates have no assigned release.
+[Broader native workloads and costs](https://github.com/eberkut/ithrl/issues/16) and
+[baseline-sharing strategies](https://github.com/eberkut/ithrl/issues/17) remain research
+opportunities. Synthetic qualification covers a planted approximately 10k workload;
+[saved-session experiments](docs/measurements.md#saved-session-experiments) add selected larger
+contexts, including incomplete and inconclusive outcomes. Neither establishes a general 100k
+workload envelope. Qualification at that scale remains an optional expansion with a separate
+cost proposal.
+
+## Planning and release policy
+
+GitHub issues track implementation scope, acceptance criteria and dependencies. Release milestones
+group this work, and the [public Project](https://github.com/users/eberkut/projects/1/views/4) shows
+status. See [decision records](docs/decisions/index.md) for rationale,
+[research](docs/research/index.md) for methods and evidence, and
+[architecture](docs/architecture.md) for the current design.
+
+Keep each issue's problem, rationale, evidence, scope and stop point self-contained. Roadmap entries
+explain direction and link to those owners; neither should depend on chat history or local plan
+files.
+
+Before 1.0, project-owned schema tags remain at `1` while formats evolve directly. Breaking changes
+are acceptable; current-format validation and evidence identity remain strict. A future stable
+release needs stable case/runner/oracle contracts, useful adapters, documented statistics,
+portable artifacts, reviewed export privacy, migrations and practical ordinary-case cost evidence.
+There is no fixed 1.0 feature list or release date.