# Changelog

> Each release keeps at most 8 outcome records of at most 512 characters.

## Unreleased

## 0.16.2: Passive first-CWD memory hotfix

- `Passive first-CWD memory`: Treats global-only storage as a valid passive-memory state before the current CWD has ever materialized, projecting an empty CWD overlay instead of warning that shared storage is incomplete; CWD-without-global storage still fails closed.

## 0.16.1: Resumed activation hotfix

- `Resumed activation`: Reasserts the selected session stream as a complete semantic cohort when `/state-flow-start` enables a resumed branch, so extension upgrades cannot misclassify retained session state as an omitted write while shared scopes still reconcile against their live owners.

## 0.16.0: Proportional State Flow guidance

- `Operational Skill`: Adds the packaged `state-flow-guide` as an on-demand reference for concrete read, patch, inheritance, acquisition, finalization, and recovery problems without triggering memory audits or unsolicited cleanup.
- `Memory Skill`: Compresses `state-flow-memory` into one bounded curation procedure while preserving authority separation, intent cleanup, evidence boundaries, ownership checks, two-phase scope transfer, external acceptance verification, and active/passive finalization behavior.
- `Contract alignment`: Updates executable Skill discovery and release-package inventory checks for both Skills, removes obsolete documentation for retired read syntax, and defines state references as structured `$ref` values or `$`-prefixed `read_state` paths in prose without proactive link scanning.
- `Reference diagnostics`: When one requested value path is missing and exact durable sources exist, returns `{value:null, hint:[...]}` with a typed reconciliation message and at most three runtime-verified current owning paths. Keys, patch, batch, and unmatched reads remain all-or-error; no match never implies that the agent invented the path.
- `Composition root`: Reduces `lib/extension.ts` to higher-level Pi lifecycle wiring by moving patch presentation into `protocol`, branch traversal into `session`, diagnostic persistence into `logging`, and durable queue/worker lifecycle into `publication`, without adding domains or changing public behavior.

## 0.15.0: Intentional agency

- `Intent semantic plane`: Adds hot, object-valued `intents` to global, CWD, session, and effective state. An intent is a selected commitment to future action, distinct from requirements in `contract`, observations or possibilities in `working`, and inactive supporting memory in `lazy`.
- `Intent lifecycle`: Supports ordinary atomic creation, update, scope overlay, supersession, and removal. Active intents survive intermediate handoffs; fulfilled, abandoned, superseded, or impossible intents disappear while consequential results and referenced state remain independently retained.
- `Explicit semantic references`: Intents may carry conventional `{"$ref":"cwd.lazy.plan"}` pointers. Reads return references exactly and follow their targets only through a separate explicit `read_state`; State Flow adds no dependency graph, automatic hydration, scheduling, execution, or completion behavior.
- `Durability and migration`: Preserves intents across hot history, Git and file-only persistence, passive and active operation, forks, compaction, and CAS conflicts. The explicit 0.14 → 0.15 migration adds empty intents to retained scopes without inferring commitments from working state, plans, requirements, lazy memory, or response prose.
- `Inspection and guidance`: Extends current, scoped, historical, key, patch, and batch reads; adds read-only Telegram intent inspection; and updates the model protocol and bundled memory Skill to reconcile active commitments without introducing a task manager or second agent loop.

## 0.14.0: Passive and progressive memory

- `Default passive memory`: Repository-root configuration now adds independently configurable passive bootstrap and `read_state`/`patch_state` access, both enabled by default. Passive reads project durable memory without mutation; explicit patches may materialize storage while episode barriers, continuation, response reconciliation, and compaction remain inactive. Start promotes to active semantics and Stop returns to passive mode.
- `Bounded array ranges`: Added strict half-open `[start:end]` selectors to `read_state` value and patch paths, with `[start..end]` accepted as a forgiving fallback spelling. Ranges are zero-based, must fit fully within the selected array, preserve ordered batch semantics, and never truncate silently.
- `Direct read paths`: Removed the redundant top-level `state` segment and legacy public `offset`/`scope` inputs. `read_state` now accepts only `path` or `paths`; unscoped semantic paths read the current effective overlay, while `effective`, `global`, `cwd`, and `session` select overlay or ownership. The injected model protocol is 25% shorter while retaining its normative contract.
- `Lazy semantic plane`: Added scope-local ordinary-JSON `lazy` state under the existing atomic temporal lineage. Ordinary projections omit lazy bodies but expose a bounded root hint; explicit scoped, effective, historical, value, and keys reads resolve lazy data through `read_state`. Telegram inspection now exposes `lazy` and represents the state step with native rich-text code rather than visible Markdown delimiters.
- `Lazy durability`: Preserved lazy values through predecessor-envelope migration, exact Git and file-only restoration, and native session forks. Invalid lazy state and stale-basis hot-plus-lazy publication now fail before changing retained hot or lazy semantics. Local incompressible-payload measurements found roughly linear current-layout growth and sub-0.5-second publication/restoration through 1 MiB, so this release keeps lazy data co-located with canonical scope semantics rather than adding speculative sharding.
- `Indexed array patches`: Extended recursive `patch_state` semantics so canonical `"[N]"` selectors update existing array elements, including nested object and array elements, while invalid indices or indexed deletion reject the complete atomic cohort.
- `Progressive historical reads`: Extended `read_state` with arbitrary path-intersected semantic `patch` projection, including ordered all-or-error batches and effective-state change projection without exposing temporal metadata.
- `Session storage ownership`: Split branch/run recovery into session `runtime.json`, leaving every scope's `meta.json` symmetric around temporal boundaries and artifact provenance. The migration domain now explicitly detects and atomically upgrades every owner-proven 0.13 session to the 0.14 contract through normal CAS publication; full specifications are removed after accepted terminal reconciliation.

## 0.13.4: Concurrent publication hotfix

- `Publication contention`: A publisher now waits briefly for a cooperating live State Flow process to release the storage or shared Git lock, preventing transient concurrent `patch_state` calls from failing while preserving explicit errors for interrupted, malformed, reentrant, or prolonged lock ownership.

## 0.13.3: Telegram section discovery hotfix

- `Telegram section discovery`: The compiled extension now resolves the sibling pi-telegram public sections membrane from its compiled layout as well as the package export, restoring the State Flow control in the Telegram main menu without making Telegram a core dependency.

## 0.13.2: Benign compaction readiness

- `Benign compaction readiness`: Automatic State Flow compaction now requires enough persisted message history as well as high total context usage, so a short session enlarged only by its system prompt remains a quiet non-action instead of surfacing Pi's native `Nothing to compact` failure.
- `Release automation`: The publish job now builds the compiled distribution before capturing its script-free local package inventory, so post-publication comparison uses the same manifest shape as the npm artifact.

## 0.13.1: Compiled package release verification

- `Release verification`: Public npm verification now checks the compiled Pi entrypoint and packaged Skill introduced in 0.13.0 instead of requiring the retired source entrypoint, with an invariant preventing the workflow from drifting back to source-package assumptions.

## 0.13.0: Semantic storage and compiled distribution

- `Semantic storage`: `checkpoint.json` and each `patches.jsonl` line now contain only semantic payloads; temporal boundaries and CWD ownership moved into `meta.json`. Explicit Start atomically converts global state, every owner-proven CWD, and every owned session in the configured store, preserving runtime/config/provenance and unknown metadata. Git-backed stores receive one new root commit; file-only stores receive the same migration without Git.
- `Compiled distribution`: Pi now executes a nested `dist/pi-state-flow/index.js` identity shim backed by compiled JavaScript and declarations. Builds also stage packaged Skills, while source entrypoints remain available for local development.
- `Versioned Telegram inspection`: State snapshots now use a less-prominent heading and include the matching monospaced `#N` State Flow step for Global, CWD, Session, and Effective views; the `State Flow: #N` button is unchanged.
- `Tool output spacing`: Successful visible `patch_state` rows and every failure path, including transport/WebSocket errors, now leave exactly one blank line between the tool heading and its output without changing patch or error semantics.
- `Patch readability`: Successful patch JSON now separates adjacent Global, CWD, and Session scopes, adjacent semantic sections such as `working` and `response`, and the final eligibility field with blank lines while remaining valid JSON.

## 0.12.1: Cleaner successful patch rendering

- `Successful patch rendering`: Successful visible `patch_state` rows now contain only valid pretty-printed JSON, without the redundant materialized-scope summary, and separate adjacent memory sections with blank lines.

## 0.12.0: Unified state reads and visible patches

- `Unified state reads`: `read_state` now resolves current-as-index-zero paths for effective/scoped materializations and retained scope patches while preserving the prior offset/scope input for compatibility. Materialization paths share the composed causal timeline; patch paths walk accepted records for their selected scope.
- `Successful patch visibility`: Interactive successful `patch_state` rows show the applied JSON arguments by default. Agent-level `showSuccessfulPatches: false` restores compact summaries; rejected calls and private validation payloads remain separate.

## 0.11.2: Single hierarchical Back control

- `Telegram inspection navigation`: Removes the chooser-owned `⬅️ Back` button from Show state. The section framework now supplies the only navigation row, `⬆️ Back`, which returns directly to the State Flow section; the four scope choices and read-only Rich state inspection are unchanged.

## 0.11.1: Telegram inspection hierarchy

- `Telegram inspection`: `👁 Show state` now follows Start/Stop, and its Back, 🌐 Global, 📂 CWD, 💬 Session, and 🧬 Effective controls form one vertical composition axis. A selected scope opens with a fixed emoji-bearing heading followed directly by the four top-level collapsible semantic fields, removing the redundant outer disclosure.

## 0.11.0: Telegram state inspection

- `Telegram inspection`: The State Flow submenu now offers `👁 Show state` with Global, CWD, Session, and Effective choices. Selecting one scope sends exactly that projected materialized slice as a standalone Telegram Native Rich Message whose semantic fields use collapsible `details` and JSON `pre` blocks; inspection is read-only and the optional adapter remains fail-open without a compatible pi-telegram membrane.

## 0.10.2: Token-guided compaction and patch resilience

- `Compaction readiness`: Early State Flow compaction now uses Pi's public context-token estimate with a 24,000-token floor instead of serialized-entry bytes, skipping unknown or short contexts without invoking native compaction. Successful shortening retains the complete latest accepted user iteration rather than only its final answer, while durable state and append-only session history remain intact.
- `Patch resilience`: `patch_state` now quietly normalizes a bounded Boolean-like compatibility set for `final`. Explicit false can accompany an atomic semantic patch or stand alone as an inert non-terminal no-op without clearing eligibility, creating history, or producing an invalid-patch diagnostic; model-facing guidance still teaches only omission and `final:true`, and ambiguous values remain invalid.
- `Memory stewardship`: Runtime guidance, tool prompts, project protocol, architecture/usage docs, and the bundled memory Skill now require narrowest-scope placement and touched-branch cleanup on ordinary handoffs, plus one bounded ownership/obsolescence reconciliation when a feature, release, campaign, project, or active version changes. Scope migration remains targeted, verified, non-background, and destination-first.

## 0.10.1: Filesystem self-healing and graceful degradation

- `Shared scopes`: A wholly absent live global/CWD checkpoint-tail pair is now distinct from partial storage. Untouched publication adopts empty current reality at a fresh origin and transactionally materializes the canonical pair without resurrecting selected values; a patch targeting the disappeared scope fails precisely for reinference. Git/file backends retain publication locks, CAS, full cold history and concurrent-writer exclusion.
- `Authority and locality`: Exact selected Git revisions can reconstruct missing private session files, while file-only loss without a retained cohort and partial session semantic/runtime pairs remain fail-closed. Missing provenance degrades freshness without invalidating semantic artifacts; malformed provenance bytes remain untouched. Existing optional config, Knowledge discovery, queue, lease, lock and external-source absence keeps its local graceful behavior.
- `Recovery evidence`: Native Pi now reconciles an ordinary answer after complete live CWD-pair deletion, then accepts another session patch and reloads/resumes the repaired state. Regression coverage also proves no shared-value resurrection, stale-target refusal, partial-pair preservation, one-owner concurrent repair, stale-capture CAS loss, exact session reconstruction, and absent/malformed operational or external-resource behavior.

## 0.10.0: Native session memory and reliability

- `Git work`: Single-use restoration, exact-path tree reads and NUL-safe index batching cut steady Git calls 120→87 and resume 63→21 without caching live bases or weakening exact-byte/CAS guards. Selected state/runtime blobs now bypass Node's implicit 1 MiB output limit, preserving large-state answers and cold restoration. Legacy/file-cohort, mode/owner and rollback checks remain. Call savings do not establish universal latency gains.
- `Queue integrity`: Commit targets and confirmations must be scalar strings across queue creation, parsing, serialization, coalescing, confirmation and asynchronous push. Arrays and other coercible values are rejected before ancestry or push effects, while malformed files remain unchanged and valid queue/CAS behavior is preserved.
- `Publication`: Dead-worker reclamation rechecks validated ownership under the queue writer gate; fresh claims and live PID/token release remain independent, and malformed/foreign records survive. Async pushes have a 15-second budget. Shutdown/native replacement cancel owned children, wait at most two seconds, retain unconfirmed leases, and fence old-generation queue writes/relaunch without losing accepted state or newer queued targets.
- `Artifacts`: Discovery prunes only owner-confirmed missing Markdown entries, preserving external/non-Markdown artifacts and state under unavailable roots; status reports unavailable freshness and cannot consume pending removals. Every model scope rejects runtime/legacy provenance writes, including field deletion, while legacy reads, semantic edits, whole-artifact deletion, and runtime-owned compilation remain valid.
- `Context`: Preflight avoids branch rebuilds; projection avoids discarded-history arrays. After eligible accepted runs, native compaction keeps the final answer and full JSONL/tree while shortening active/resumed entries without another model summary; threshold/overflow remains Pi-owned and foreign context blocks shortening. Mid-run Stop retains tools/results. Status JSON renders only effective memory; scoped diagnostics and `read_state` remain.
- `Integrity`: Runtime-only Stop preserves newer shared provenance; cold reads pair it with the selected semantics. Separate-process witnesses cover running/resumed sessions and fatal Git writers before/after ref advancement across same/different CWDs. Accepted history, other sessions' private files and caller index bytes survive. Interrupted publication locks remain intact; new writes and restore installation fail closed without resetting selected memory.
- `Validation and guidance`: The final 426-test suite passes on Pi/AI/agent-core 0.84.4; affected compaction/status/native lifecycle checks and typecheck also pass on 0.85.1. Matched long-session controls retain source/resource/exit evidence and adverse timings. Read telemetry separates delivered bytes from truncation; oversized reports reject faux errors. Top-level `benchmarks/` owns opt-in workloads; indexed guides document limits.
- `Fork`: Native same-CWD fork replacement copies the selected session checkpoint, retained tail and provenance into a distinct owner over unchanged current shared layers. The child starts its own origin/checkpoint; parent data/history and CAS remain intact. Owned reload/resume and independent writes are covered. Inherited parent pointers cannot fall through to a reset marker, and parent Stop projection cannot resurface after child reload. Missing/unsafe source evidence fails closed.

## 0.9.6: Monospaced state value in the submenu

- `Interop`: The submenu help line now consists solely of the operator-specified sentence "Records the latest accepted state after every turn, so a new session resumes from the last committed point."; the trailing "Start it to keep memory live on this branch, stop it to pause." sentence was removed.
- `Interop`: The submenu state line renders the live value in monospace — `off` or `#N` — while the section button keeps the same plain-text label.

## 0.9.5: Shorter submenu help line

- `Interop`: The submenu help line now opens directly with "Records the latest accepted state after every turn…"; the "Durable memory for this conversation: State Flow" prefix was removed at the operator's request.

## 0.9.4: Telegram submenu mirrors the status line

- `Interop`: The section button always carries the spiral identity and the live value — `🌀 State Flow: off` while disabled, `🌀 State Flow: #N` while enabled; the black-circle variant is gone.
- `Interop`: The submenu header repeats that same state line and follows it with a short explanation of what State Flow is; the only action is one wide `Start` or `Stop` button, with the transport's `⬆️ Main menu` row above it. Refresh and Cancel start are no longer presented, the verbose status block was removed, and their callbacks stay routable for keyboards from earlier versions.

## 0.9.3: Publication queue lineage-rewrite hotfix

- `Publication`: Retarget a queued target orphaned by a journal reset or re-initialization to the live lineage and keep publishing, instead of failing every `turn_end` with "Publication queue targets diverge"; the retired commit stays in local Git history.
- `Diagnostics`: Record the retired target in opt-in diagnostics and report a deferred remote publication accurately instead of claiming the final response could not be reconciled.

## 0.9.2: Single Telegram surface

- `Interop`: State Flow now appears on Telegram exactly once. The inline main-menu section button before Settings carries the live status (`🌀 State Flow: #N`, `⚫️ State Flow` while off) and opens the existing start/stop submenu; the duplicated Status-screen row is removed, so the same value no longer renders in two places. Fail-open registration and shutdown disposal are unchanged.

## 0.9.1: Status text mirrors the terminal line

- `Interop`: The `pi-telegram` surfaces now copy the compact terminal status instead of decorating it. The Status screen shows the terminal value itself (`State Flow: #N`) and hides entirely while State Flow is off; the main-menu button shows `🌀 State Flow: #N` or a plain `⚫️ State Flow` without on/off, starting, bootstrap, or separator text.
- `Testing`: The shared test harness removes its temporary fixture repositories at process exit; runaway fixtures previously exhausted the `/tmp` inode table and made later runs fail with ENOSPC.

## 0.9.0: Telegram status surface

- `Interop`: Added an optional fail-open `pi-telegram` presentation adapter. With the transport installed, the status screen shows `State Flow: on · step #N` while enabled, and the inline main menu places a `🌀 State Flow: #N` or `⚫️ State Flow: off` section button directly before Settings.
- `Control`: The section submenu exposes the branch lifecycle already owned by the commands: Start, Stop, Refresh, and Cancel start while a start deferred behind an active run is pending. A busy start waits for the current run to settle, Stop applies immediately, and the adapter calls the same start/stop functions as `/state-flow-start` and `/state-flow-stop`.
- `Compatibility`: Registration fails open when pi-telegram is absent or its section registry is not ready, retries on session start, and disposes on session shutdown. Core semantics, storage, inference, and hosts without pi-telegram are unchanged.

## 0.8.1: Preserved answers and bounded fallback resolution

- `Resolution`: A terminal draft is never discarded. A draft ending before eligibility — or an eligible draft whose final validation fails for a later acquisition — is preserved as the runtime-owned response at `turn_end`, then at most two same-run fallback turns exist only to obtain the `final:true` patch. Fallback turns never enter `response`; success commits their patches with the preserved answer intact, and exhaustion closes the iteration with the preserved answer, current state, one bounded warning, and a finalization diagnostic.

## 0.8.0: Atomic cohorts and final eligibility

- `Protocol`: Replaced the single-scope PATCH and UNCHANGED forms with one canonical `patch_state({global?, cwd?, session?, final?})` call. Supplied scopes validate against one causal basis and publish as one atomic transition with a single identity, temporal boundary, durable cohort, and inference barrier; unknown fields, `final:false`, empty scopes, and material no-ops fail closed.
- `Eligibility`: `final:true` is now an ephemeral per-iteration latch rather than a resolution form. It permits a later `turn_end` without stopping reasoning, tools, or further patches; eligibility survives later activity and repeated final calls, resets only with the next enabled iteration, and `{final:true}` alone creates no semantic transition, identity, step, or Git commit.
- `Resolution`: An ineligible terminal draft is discarded and steered for at most three attempted completions. The first two attempts emit hidden same-run instructions; the third reports one bounded error while preserving committed state, enablement, and runtime-owned response. Failed and host-rejected patch calls consume no attempts, and only the accepted post-eligibility answer becomes `response`.
- `Diagnostics`: Rejected `patch_state` calls now retain their exact attempted arguments alongside the precise error, tool identity, call id, resolution-attempt count, and terminal-eligibility state; publication conflicts use the same record and successful patches are never logged.
- `Compatibility`: Persisted checkpoints, tails, provenance registries, scope layout, and Git/file durability are unchanged and need no migration; the removed model-facing grammar is not accepted as a compatibility alias.

## 0.7.0: Explicit resolution and leaner runtime

- `Protocol`: Made `patch_state` the sole model-authored semantic mutation path. Every enabled turn now requires a successful resolution call, each exactly PATCH `{scope, patch}` or UNCHANGED `{"unchanged":true}`; unresolved prose is discarded and steered within the same run, failed calls remain unresolved, and only the later accepted ordinary answer becomes runtime-owned `response`.
- `Stop`: `/state-flow-stop` still creates no semantic transition, but now prevents raw-history resurrection with a frozen effective-state handoff plus post-stop messages. The bounded projection survives reload, resume, and tree restoration for that physical session; active restart uses the same boundary for one migration run, while new/forked sessions inherit nothing.
- `Metadata`: Moved artifact source hashes, compiler revisions, and compilation timestamps from model-visible artifacts into each scope's existing `meta.json`. Missing evidence degrades only dependent freshness capabilities, malformed present evidence fails locally, and legacy embedded provenance remains readable compatibility input but is stripped from projection.
- `Temporal`: Removed configurable `transitionWindow` output in favor of one fixed seven-boundary hot history, while tolerating retired input. Restored branches now adopt proven advances in untouched global/CWD streams at a fresh origin and fail precisely when the current patch targets a shared scope that diverged; publication CAS still protects the captured basis.
- `Durability`: Git publication now commits the complete non-ignored state-repository delta, including tracked edits, new files, and manual deletions, before overlaying exact prepared State Flow bytes. Active files retain CAS protection, ignored files remain untouched, rollback preserves concurrent bytes, and the caller-visible index is synchronized to the accepted tree.
- `Activation`: Normal `turn-end`/`off` activation accepts locally without waiting for remote push, Markdown freshness discovery is deferred until the next enabled inference, and canonical stores skip full predecessor-format planning when legacy snapshot names are absent. Warm reactivation has one config commit; timing and Git Trace2 evidence are recorded in the architecture guide.
- `Diagnostics`: Added opt-in local JSONL diagnostics for rejected `patch_state` calls and intercepted unresolved drafts, excluding reasoning bodies and all semantic/publication planes. Logging failure is inert apart from one warning. Failed `patch_state` results remain real errors with a local blank-line rendering boundary.
- `Compatibility`: Preserved the four-field semantic shape, three scopes, storage paths, existing 0.6.x stores, optional Git/file durability, and remote policy without a bulk migration or new metadata file. Removed the terminal HTML-comment parser/retry protocol and its validation module; historical and foreign comments remain ordinary owner-controlled text.

## 0.6.0: Continuity without fixation

- `Memory`: Revised ordinary handoffs to preserve confirmed decisions, useful uncertainty, interaction consequences, completed prerequisites, bounded positive and negative results, and exact continuation without promoting provisional methods or unsupported assertions.
- `Skill`: Expanded the explicit `state-flow-memory` Skill with reframing, one bounded fresh-run review, compilation-first scheduling, write/readback/delete scope migration, recoverable partial results, and evidence-gated external promotion.
- `Curation`: Added regression coverage for the executable curation barrier sequence while preserving single-scope `patch_state`, terminal multi-scope reconciliation, trusted compiler metadata, native tool context, and local acceptance independently from remote replication.
- `Compatibility`: Preserved the 0.5.0 semantic shape and Git/file storage without migration, bulk rewrite, new dependency, or new runtime/config/tool contract.

## 0.5.0: Durable memory, compiled routing, and local-first publication

- `Publication`: Decoupled immediate local Git acceptance from optional remote replication with persisted `off`/`turn-end`/legacy `transition` policy, a symlink-safe CAS queue, descendant-only coalescing, asynchronous non-interactive workers, restart recovery, concurrency-safe confirmation, and truthful status diagnostics.
- `Memory`: Made State Flow the unconditional durable-memory owner while enabled, with global semantic memory always available at the narrowest correct scope; external promotion pointers remain optional semantic handoff records rather than runtime ownership configuration.
- `Artifacts`: Added extensible compiled artifact metadata, validated tags, deterministic candidate routing, and bounded visible source rehydration without persisting source bodies or treating routing as read authorization.
- `Continuation`: Added read-only native-session discovery, exact State Flow provenance checks, deterministic continuation ranking, and bootstrap planning while keeping automatic default resume deferred until Pi exposes a pre-session resolver hook.
- `Identity`: Unified Pi's session UUID and native storage key as one runtime address, centralized extension runtime construction, and skipped obsolete hashed-path probing once canonical CWD materialization is proven.
- `Validation`: Replaced transient semantic-equality SHA-256 calculations with validated structural JSON comparison while retaining cryptographic hashes for durable identity, freshness, integrity, CAS, and fingerprints.
- `Transcript`: Restored the empty-line boundary between the `patch_state` tool call and its materialization result in Pi and Telegram transcript rendering.
- `Skill`: Bundled the optional `state-flow-memory` Skill for explicit bounded audits, scope narrowing, contradiction cleanup, and evidence-gated external handoff without background maintenance.

## 0.4.0: Temporal state and independent durable storage

### Temporal state

- `Temporal`: Rebuilt materialized state on one parent-linked causal lineage. `state[0..7]` and each global/CWD/session projection now resolve the same accepted boundary, sparse multi-scope changes share one identity, response-only changes advance history, and semantic no-ops do not.
- `Temporal`: Added enabled-only `read_state` for lazy effective or scoped reads at offsets zero through seven. Reads use the cached checkpoint/tail runtime without publishing, while `patch_state` remains the sole mutator and an immediate inference barrier.
- `Lifecycle`: Preserved Pi's native tool loop and full inspectable session trace while reconciling each finalized answer into session response exactly once. New sessions inherit shared scopes without rewriting them; resume, tree navigation, stop, and pre-runtime branch starts preserve branch-local provenance.

### Storage and recovery

- `Storage`: Moved runtime state out of Knowledge into the independently configurable `agentDir/state-flow` store. Canonical scope files are anchored `checkpoint.json` plus bounded replayable `patches.jsonl`, with separate session `config.json` and `meta.json`; strict revision-only Pi checkpoints replace copied semantic snapshots.
- `Storage`: Made Git optional. File-only mode preserves the exact current cohort and hot history when the executable is absent; Git mode commits every accepted cohort immediately, keeps local-only repositories valid, retries the exact commit after remote failure, and adopts populated file stores without inventing earlier history.
- `Identity`: Aligned CWD and session directories with Pi's native readable layout, including JSONL filename stems and header-derived in-memory session names. Canonical owner metadata retains collision/foreign-identity checks; current Git-backed SHA-suffixed development stores migrate transactionally, while old Git revisions remain readable.
- `Recovery`: Added conservative current-state migration and branch restoration without checkout/reset. Historical reads select Git objects directly; unavailable pointers never authorize substituting live files, and changing the configured store does not silently relocate Knowledge-backed history.
- `Publication`: Hardened publication with shared exclusion, isolated indexes, exact prepared-byte receipts, compare-and-swap checks, symlink/path rejection, unrelated staging preservation, and conflict-aware byte-exact rollback.

### Configuration, context, and diagnostics

- `Configuration`: Added strict agent-level `state-flow.json`: `directory` selects storage and `autoStart` defaults to `false` for genuinely new sessions only. Absolute, config-relative, and home-relative paths are supported; SDK storage and Knowledge roots remain independent overrides.
- `Context`: Retained the canonical `artifacts`, `contract`, `working`, and `response` semantic shape, with recursive global → CWD → session overlay. Knowledge Markdown and Skill acquisition now use source-addressed, runtime-hashed artifact compilations and materialized-first read policy rather than raw-body injection.
- `Diagnostics`: Expanded status and acceptance documentation for selected revisions, active temporal boundaries, hot-history depth, retained scope tails, artifact freshness, pending publication, unavailable materialization, and all twenty temporal properties.

## 0.3.0: Optional memory patches and evidence-aware handoffs

- `Reality`: Require targeted revalidation of volatile observations and inspection of external effects after interruption or branch navigation; missing memory proves neither success nor absence of effects. Document the absence of rollback/freshness guarantees and preserve the restriction on routine Skill rereads. Add instruction-presence tests, not semantic or integration guarantees.
- `Memory`: Strengthen the handoff protocol with evidence-aware continuation, requirement/observation/hypothesis distinctions, conditional rejections, and contradiction reconciliation; preserve decision-relevant uncertainty during optimization. Add instruction-presence regressions, not semantic guarantees. Increase the protocol-only character budget to 3,700 (3,900 with bootstrap) for these obligations; state remains uncapped.
- `Terminal`: Accept ordinary non-empty terminal answers as empty memory patches: preserve memory and update the response without unnecessary regeneration, including answers split across text blocks.
- `Validation`: Keep malformed explicit envelopes and missing Skill compilations on the existing bounded validation path.
- `Planning`: Clear the backlog; documented integration and continuation-quality limitations remain, not release commitments.

## 0.2.3: Document protocol and validation limitations

- `Terminal`: Document that duplicate-comment detection also rejects literal State Flow envelope examples inside fenced or inline code in terminal answers, and provide a plain-JSON workaround.
- `Validation`: Clarify that mock lifecycle tests are not real Pi scheduler integration checks and that structural validation cannot guarantee semantic memory retention.
- `Runtime`: No runtime behavior changes.

## 0.2.2: README structure hotfix

- `Documentation`: Separate installation from usage, remove the redundant quick-start section, and move architecture details after the user-facing documentation.

## 0.2.1: README banner hotfix

- `Documentation`: Add the project banner to the README.

## 0.2.0: Modular runtime hardening

- `Documentation`: Add a task-first README quick start with explicit compatibility, opt-in behavior, one-off trial instructions, and Pi package security guidance.
- `Protocol`: Tighten the normative runtime protocol and enforce a regression-tested character budget; omit absent validation feedback from synthetic runtime context instead of serializing a redundant `null`.
- `Testing`: Redistribute lifecycle coverage from the former monolithic extension suite into the corresponding mirrored domain suites, leaving `extension.test.ts` focused on composition and using one shared test harness.
- `Architecture`: Split the runtime into independent `json`, `state`, `episode`, `snapshot`, `session`, `recovery`, `status`, `context`, `skills`, `terminal`, `validation`, `transition`, and `extension` modules under `lib/`; isolate explicit episode transitions, active-branch selection and recovery, status rendering, bounded retry decisions, atomic state staging, and compare-and-swap commits; mirror each domain under `tests/`, enforce an acyclic dependency graph with cross-domain invariant tests, and reduce `index.ts` to composition and public exports.
- `Lifecycle`: Register lifecycle commands in the canonical start, status, stop order.
- `Context`: Centralize synthetic runtime-context construction and private validation-message filtering in the independently tested context domain, keeping user-controlled specifications out of system-prompt composition.
- `Recovery`: Keep State Flow enabled and preserve the last committed state when terminal-validation retries are exhausted; only the transient retry chain is abandoned so the next user request can continue reliably.
- `Skill`: Track Skill reads through an independently tested lifecycle correlator in Pi's actual `tool_execution_start` → `tool_call` event order while retaining the mutable intercepted input reference, so later argument rewrites are attributed to the executed path.
- `Lifecycle`: Discard mismatched lifecycle records defensively so a stale or reused tool-call id cannot produce false Skill acquisition.
- `Validation`: Bound restored iteration and validation-attempt counters before incrementing them, reject exhausted live iteration counters explicitly, and cover both safe-integer boundaries so malformed branch metadata cannot corrupt retry accounting or status output.
- `Validation`: Reject restored non-JSON state values such as non-finite numbers before they can break hashing or silently materialize as `null`.
- `Recovery`: Fall back past malformed newer checkpoints to the newest valid active-branch snapshot, while still failing closed on cyclic or hostile snapshot objects when no valid checkpoint remains.
- `Recovery`: Reject malformed three-field state shapes rather than reinterpreting them as legacy working memory, and contain failures while enumerating hostile branch entries.
- `Validation`: Make canonical serialization and exported patch validation reject lossy or cyclic non-JSON inputs explicitly instead of returning invalid results or silently rewriting values.

## 0.1.5: Skill attribution and state model clarification

- `Skill`: Attribute successful Skill acquisition to finalized `tool_execution_start` arguments, with a tested compatibility fallback to the intercepted `tool_call` input.
- `State`: Clarify that the three-field materialized handoff coexists with mutable exogenous project and runtime state that can also shape model behavior.
- `Documentation`: Remove the obsolete `/reload` step from the usage instructions.

## 0.1.4: Release verification hotfix

- `Release`: Kept npm pack lifecycle output out of release inventory JSON so Trusted Publisher releases can complete public verification and GitHub Release creation.

## 0.1.3: Trusted Publisher release automation

- `Release`: Added immutable-tag GitHub Actions automation that validates the package, publishes and verifies npm through Trusted Publisher with provenance, and creates the matching GitHub Release.

## 0.1.2: Repository identity hotfix

- `Identity`: Aligned GitHub repository, package metadata, installation documentation, and release links under the canonical `llblab/pi-state-flow` identity.

## 0.1.1: Public npm distribution

- `Release`: Enabled public npm distribution for `@llblab/pi-state-flow`, including registry access and verified GitHub package metadata.
- `Skill`: Clarified that compiled Skill knowledge is stored persistently under `contract.compiled_skills`, never as another top-level state field.

## 0.1.0

- `Runtime`: Added an opt-in State Flow runtime inspired by SKILL.state, with argument-free lifecycle commands, per-user-run specifications, active-branch persistence, and one materialized explicit state.
- `Lifecycle`: Added native Pi tool-loop preservation: tool-bearing responses require no patch, current-run tool trajectory remains model-visible, and one terminal handoff commits state after the complete agent run.
- `State`: Added required flexible `contract` and `working` objects plus the required latest user-facing `response` string, recursive materialization, nested object-key `null` deletion, materialized-null rejection, and deterministic state compare-and-swap.
- `Terminal`: Kept arbitrary response content outside the transcript-private `<!-- state_flow … -->` memory-patch frame; the runtime strictly anchors the frame at the start of one terminal text block, requires exactly one blank separator, reconciles materialized `response` with Pi's finalized post-handler text at `turn_end`, and routes post-handler finalization failures through the same bounded hidden regeneration chain. Documented that the frame remains observable to streaming consumers before finalization.
- `Authority`: Kept user-controlled turn specifications at user authority by moving their repeated representation out of the system prompt and into synthetic user runtime context, including support for empty text in image-only prompts.
- `Recovery`: Added active-branch restoration after `/tree` navigation, clean abandonment of interrupted terminal-validation retries before the next user run, and cumulative retry accounting across intervening tool-bearing turns.
- `Context`: Preserved persistent and current-run custom context from other Pi extensions, attributed Skill acquisition from finalized executed arguments after mutable tool interception, and limited accidental intermediate-envelope stripping to a structurally valid leading frame.
- `State`: Hardened recursive patch materialization so JSON keys such as `__proto__` remain ordinary own data without changing object prototypes.
- `Packaging`: Added an explicit release file allowlist, Pi package discovery keywords, package-safe README targets, Pi/Node compatibility bounds, and a prepack validation gate so generated packages contain only runtime and human-facing release files.
- `Bootstrap`: Added bootstrap migration for enabling State Flow inside an existing session, per-run specification rotation, schema-free episode-level Skill compilation in `contract.compiled_skills` keyed by exact source path, and model-owned memory optimization that reorganizes inefficient structure and deletes stale, redundant, speculative, or low-value state.
- `Architecture`: Removed per-tool state commits, action authorization, Delta Window, observation envelopes, action ledgers, project schemas, state and patch byte caps, dynamic growth pressure, and all coupling to other extensions.
- `Protocol`: Compressed the static runtime protocol while retaining terminal, handoff, Skill-compilation, authority, and memory-optimization invariants.
- `Lifecycle`: Added stop-as-complete-episode-reset semantics, a compact accent `state-flow` plus dim `#<iteration>` status, and complete pretty-formatted state JSON output from `/state-flow-status`.