# Changelog

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

## 0.26.4: Passive Compaction Continuity

- `Passive continuation`: After idle Stop, native compaction can replace the later user anchor with a summary. Passive now retains that summary, the available tool calls/results and later refinements instead of reducing requests to a frozen handoff. Reload/resume preserve the same continuation; discarded raw history is not reconstructed. Native compaction, memory scopes and stored state are unchanged; no migration or configuration change is required.

## 0.26.3: Passive Response Isolation

- `Passive context`: Automatic Passive memory heads, Stop handoffs and state-update receipts omit the `response` plane, including after reload and mode changes. Active still sees the previous accepted answer. Canonical response storage, explicit reads and native/user/tool history are unchanged; no migration or configuration change is required.

## 0.26.2: Automatic Response Guidance

- `Response ownership`: Active/bootstrap and Passive prompts explicitly forbid patching `response`; the `patch_state` guidelines forbid it in Global, CWD and Session, including clearing/deleting it, and explain that Active mode captures the final answer automatically. Runtime validation and answer capture are unchanged. No migration or configuration change is required.

## 0.26.1: Consistent Temporary Paths and Mode Colors

- `Telegram mode colors`: The selected mode uses 🟣 Off, 🟡 Passive or 🟢 Active; unselected options remain ⚫️. Mode behavior and callbacks are unchanged.
- `Diagnostic directory`: New diagnostics and Git push failure logs use `<agentDir>/tmp/pi-state-flow/logs.jsonl`, matching the Pi extension temporary-directory naming convention. Older `tmp/state-flow` logs are left untouched; canonical `state-flow/` memory storage is unchanged.

## 0.26.0: Stable Modes

- `Step-independent memory`: Memory no longer depends on the Pi step. Startup, reload, resume and `/tree` attach the current same-session JSON state; native checkpoints supply only mode and run lifecycle. Old or expired branch points never block or rewind memory. Forks copy the parent's current memory. Past values remain readable through `read_state` offsets within retained history.
- `Removed boundary restoration (library API)`: With nothing left to rewind, `withRestoreTransaction`, `prepareBoundaryRestore`, `restoreBoundary`, `acceptRestoredOrigin`, `prepareBoundaryFork`, `HistoryBoundaryExpiredError` and the temporal boundary selectors are removed. `withForkTransaction(source, lifecycle, …)` now copies the parent's current memory inside its transaction; `lifecycle` carries only mode/bootstrap. Library consumers attach current memory through `withStartTransaction`.
- `Stable Passive`: Explicit Passive accepts validated current memory like Active and stays writable across reload, including after a failed mode write. Writes stay paused only while current memory is missing, corrupt, contradictory or unpublishable; failed retries add no duplicate fence.
- `Truthful blocked status`: Unreadable current memory under Active retains Active policy and shows `active (blocked)` in terminal/Telegram, instead of a hidden fence behind an Off indicator. Active or Passive accepts repaired memory; Off releases inference only. Status explains the block and recovery.

## 0.25.5: Active Restoration Fence and Codemode Compaction

- `Active restoration fence`: Failed retained Active restoration aborts live inference instead of silently exposing native history under an inactive fallback. Expired tree/reload and contradictory-lineage native tests prove zero provider calls and unchanged memory. Valid selection, accepted Start or explicit Passive/Off releases the fence; historical authority is never substituted.
- `Codemode-safe compaction`: Exact native `codemode-store` metadata no longer blocks completed-history compaction. Full branch records remain intact; native Codemode reads prove values and deletions survive compaction, reload and resume. Unknown metadata and visible custom context remain protected.

## 0.25.4: Empty-Object Cleanup and Deletion Hints

- `Safe missing deletions`: Deletion-only patches through absent ancestors succeed without creating data or blocking other writes. Missing authored targets report their owner-scoped JSON Pointer and first unavailable component; hints remain outside state/history and create no revisions. Mixed new objects process `null` as deletion markers. Stored null and array-index deletion remain rejected; ordinary repeats and intent cascades stay quiet.
- `Recursive empty-object cleanup`: Accepted supplied scopes and response-owned Session omit empty object fields/planes, before ownership and after cascades/compilation. Explicit `{}` carries no retained value; roots, array slots and empty arrays survive. Model context hides legacy empty branches; untouched scopes and exact historical reads/replay remain unchanged. Cleanup can reveal inherited values and is recorded once as ordinary deletions.

## 0.25.3: Readable Telegram Inspection

- `Readable inspection`: Telegram memory inspection shows large fields as direct pretty-printed JSON prefixes instead of JSON-encoded `preview` strings with escaped layout and quotes. A separate notice reports omitted characters. Transport-aware budgeting preserves the Rich message ceiling and Unicode boundaries; genuine JSON string escapes, stored state and exact `read_state` results remain unchanged.

## 0.25.2: Single Patch Display

- `Single patch display`: Interactive `patch_state` rows show JSON arguments once in the call, followed by the actual acceptance, no-op or error acknowledgement instead of a second patch. `showSuccessfulPatches: false` hides call arguments while retaining compact acknowledgements; rejected arguments remain visible. Atomic publication, stored state and model-facing `state_updates` receipts are unchanged.

## 0.25.1: Cascade Receipts

- `Composition ceiling`: One invariant now counts mutable closure bindings plus `OwnedOperationSlot` and `RenewableLifetime` instances in `lib/extension.ts`, including const-bound holders, against the current total of 24 (17 + 5 + 2). Existing named owner assertions remain. Mutation checks reject an added binding, operation slot or lifetime; lifecycle source and behavior are unchanged.
- `Cascade receipts`: `state_updates.cascaded` lists every owner-scoped target removed by intent deletion, including nested lazy keys invisible to effective updates and top-level navigation. Paths only, never bodies; deterministic across scopes and never elided as predictable. Staging passes its existing cascade to the context projection without recomputing ownership or changing stored records. Native Active/Passive tests verify each scope, and the always-injected protocol did not grow.

## 0.25.0: Intent-Owned Memory

- `Intent-owned memory`: Deleting an intent deletes same-scope `working`/`lazy` keys its structured `{"$ref"}` values own, after authored operations in one atomic cohort/revision, unless a surviving intent references the target, an ancestor or descendant. Other targets and textual `$path` mentions are skipped silently; no rejection, warning or archive. Records store explicit deletions; receipts report effective changes and top-level lazy navigation, but omit nested lazy targets (fixed in 0.25.1).
- `Work from intents`: Protocol, `patch_state` description, both Skills, README and docs present `intents` as the queue of chosen actions and `working` as their temporary context. Structured refs inside intents own; textual `$path` mentions only use. Before closing an intent, save survivors to unowned paths, with abandonment reasons in `contract`. Unowned entries stay legal. The always-injected protocol did not grow; duplicated read-path and barrier wording now lives only in the tool definitions.
- `Ownership status`: `/state-flow-status` adds a per-scope `Scope memory:` block with UTF-8 sizes of present planes and the share of top-level `working`/`lazy` entries owned by an open intent. Operator-only; no notices, thresholds or model-facing effects.
- `Composition root step one`: Completed-history compaction request state moves into `StateFlowCompactionRequests` and settled-turn backup/push state into `SettledTurnBackup`, cutting `lib/extension.ts` mutable closure bindings from 34 to 26 and adding an invariant ceiling. No behaviour change.
- `Lifecycle review`: `lib/extension.ts` mutable closure bindings drop from 26 to 17 under the invariant ceiling. Artifact invalidations/hints move into `ArtifactAcquisitionState`, five lifecycle operations share one `OwnedOperationSlot`, renewable lifetimes and the session-identity guard have one owner each, and `noUnusedLocals`/`noUnusedParameters` guard dead code. No behaviour change.
- `Readable documentation`: Human-facing guides use short sections, explicit operation steps and resource-specific recovery rules. They describe current behavior rather than release chronology; performance documentation retains reproducible workloads and metric limits, not obsolete measurements. The acceptance map includes intent ownership and lifecycle owners, and a test checks relative documentation links and anchors.

## 0.24.0: Memory-Inert Off and Pi 1.0

- `Memory-inert Off`: Off startup, resume, reload, tree navigation and automatic callbacks perform no semantic-store I/O or recovery reporting, even with logging enabled. Switching to Off cancels owned memory waits and clears model tools/context without altering accepted memory; native mode, continuation, write-fence and pending-fork policy survive.
- `Safe reacquisition`: Passive restores the selected retained private boundary over live shared memory; Active validates current same-session memory. Pending Active can be cancelled or superseded by Passive without losing deferred history or inventing a write fence. Cold pending forks still require their exact proven source; expired history fails closed and bootstrap handoffs remain intact.
- `Read-only inspection`: Explicit Off inspections use disposable current-store readers, never install model cache or mutate stored bytes, mode, fences or deferred selection. Session/Effective require validated same-session authority rather than fabricated empty or foreign private state; revisions describe the inspected view.
- `Owned background work`: Off/shutdown cancel only owned backup captures and Git pushes, drain resources without late warnings and preserve accepted commits. Completed agent operations do not cancel admitted background pushes. Stale State Flow compaction requests cancel without model-summary fallback; old completion cannot clear a newer plan, and native operator/threshold compaction remains unchanged.
- `Pi 1.0 and packaging`: Requires matching Pi packages at 1.0.0 or newer and pins local verification to 1.0.0. Token estimation uses coding-agent's public export, fixing the removed agent-core API; the transitive brace-expansion patch is locked to 5.0.12. The npm package declares MIT licensing and includes LICENSE. Canonical storage formats and scope ownership remain unchanged.

## 0.23.0: Off by Default and Mode Controls

- `Passive footprint clarified`: When selected, Passive always declares both memory tools, but contributes protocol and projected memory only with a validated view; a source-bound empty/nonempty byte probe documents the distinction without claiming provider token costs. Off removes State Flow's model-facing tools and context.
- `Barrier diagnostics`: With opt-in logging, blocked Active tool calls now record `barrier-block` with the exact reason, call identity and batch tool names, never sibling arguments or reasoning. Passive has no barrier; logging-off blocks remain unrecorded. Blocking and canonical state behavior are unchanged.
- `Focused onboarding`: README keeps installation, three-mode behavior and state model; status and Telegram rendering details live in usage, including a concrete revision-vector example.
- `Toolchain ranges`: Declare `typescript` `^7.0.2` and `@types/node` `^26.4.0` in package and lockfile metadata, matching installed/locked versions instead of floating `latest` across major refreshes.
- `Contract map and compaction`: Reduce `AGENTS.md` from 8,141 to about 1,300 words, with one-line owner links; relocate missing normative detail to architecture/usage and map all 56 former paragraphs to current contracts or tests. Keep storage semantics and `tests/invariants.test.ts` unchanged.
- `Off by default`: New sessions without a configured mode now adopt Off without initializing semantic storage; explicit global modes and legacy flag mappings still apply, and resumed sessions keep their selected mode. Passive and Active remain opt-in; stored memory is not erased.
- `Telegram mode radios`: Replace the lowercase mode row and redundant list with `Off | Passive | Active` radio labels (⚫️ inactive; 🟡/🟣/🟢 selected). Matching Mode and Inspect memory headings and blank-line-separated settings-style lists explain the workflow progression and scope buttons, including inspection in Off. Callback routing and four direct scope buttons remain unchanged.

## 0.22.0: Sparse State and Session Modes

- `Sparse semantic memory`: Checkpoints and retained patches may omit documented planes. Readers and writers select only known top-level fields while preserving nested data, causal identities and history boundaries. Current and historical views omit absent fields and empty responses; explicit reads of absent documented fields return `null`. Reads and activation do not normalize stored bytes; malformed data and unproven authority still fail closed.
- `Minimal updates`: Patches emit only actual known-field changes without filling absent planes. Empty and absent responses are projection-equivalent: clearing a nonempty response creates a transition, but replacing absence with an empty string does not. No-ops advance no scope revision; retained empty records retain their identities.
- `Session-owned modes`: `/state-flow-active`, `/state-flow-passive` and `/state-flow-off` replace Start/Stop. Active runs state-driven episodes; Passive (the new-session default) exposes memory tools and state context with ordinary conversation; Off exposes neither. Global `mode` affects only new sessions. Inactive choices persist in Pi before semantic initialization and leave semantic revisions and existing write fences unchanged; legacy flags remain readable.
- `Focused controls and inspection`: Terminal shows `state-flow active/passive` or hides in Off; revisions move to `/state-flow-status`, whose semantic JSON separates top-level planes. Telegram shows a lowercase mode value with four direct scope buttons and the revision vector in Effective inspection. Pending mode selections, read-only recovery and revoked receipts cannot overwrite a newer choice.

## 0.21.0: Minimal Reconciliation

- `Sparse acceptance receipts`: Predictable direct/indexed writes, object replacements, disjoint scope writes, explicit Session scalar/array overrides, unchanged-effective deletions, artifact merges and complete lazy-navigation updates omit redundant semantic tails. Shared drift, changed hints, unknown fallback and ambiguous overlap still reconcile; lazy bodies and provenance stay hidden. Canonical storage, revisions and lifecycle formats are unchanged.
- `Acceptance and projection safety`: Artifact prediction against a masked effective array cannot turn an accepted scoped patch into a tool failure. Conservative reconciliation preserves the successful acknowledgement. Native active, passive and Stop-handoff regressions cover accepted storage, while prefix probes distinguish predictable acceptance from a minimal shared-surprise tail without rewriting earlier context.

## 0.20.0: Cache-Stable Projection

- `Cache-stable model projection`: Active/bootstrap heads freeze per accepted iteration; passive heads survive ordinary user turns. Native/mode boundaries rebase without semantic changes. Patch receipts and stable-position notices deliver current values, hints and invalidations without rewriting prior prefixes. Volatile projection IDs keep retained old results historical after rebasing. Native regressions cover repeated barriers, passive continuation and bootstrap; canonical history is unchanged.
- `Accepted-state patch tails`: Successful active/passive patch results carry projected effective replacements and deletions for touched paths and transaction-adopted shared drift, including correct repeats and scope fallback/masking. Lazy bodies and artifact provenance stay hidden; changed bounded lazy navigation remains available. Native tests prove the next inference sees these values in active, passive and Stop-handoff modes. Interactive acknowledgement and patch-display policy stay unchanged.
- `Trajectory-dominant prefix evidence`: Opt-in v3 reports exercise active, passive and Stop-handoff projection with six 20 KiB native reads before a patch and two before another. Reports retain every inference's byte prefix and read volume; native content, accepted barriers and completion are checked independently of provider callbacks. Source-bound baseline measurements distinguish frozen Stop handoff from regenerated active/passive heads without claiming provider cache-hit rates.
- `Minimum-Node benchmark validation`: Optional `BENCH_REPORT_PATH` writes complete machine-readable reports independently of test-runner stdout chunking, while retaining human-readable stdout. Regression tests read file reports for successful and failed workloads, including 1 MiB backpressure. Release validation now covers Node 22.19.0 and Node 24; publication remains on Node 24.

## 0.19.1: Lazy Isolation and Task-Driven History

- `Lazy projection isolation`: Automatic recent transitions omit entire lazy patches, including deletions, and discard empty visible records without renumbering history. Hot changes, artifact metadata filtering and bounded lazy navigation remain available. Canonical state/history, explicit reads and already communicated user/tool/response text are unchanged.
- `Task-driven history`: Missing paths and runtime hints do not require historical search. Active/passive guidance and both Skills permit targeted historical reads when useful to the task, without separate user permission, while forbidding automatic resurrection of deleted memory. Dangling-reference hints describe current reference owners, not relocated targets or recovery duties; existing lookup bounds and projection rules remain intact.

## 0.19.0: Awaited Memory and Lossless Mode Changes

- `Lossless context toggles`: Stop retains uncompiled conversation through Start/Stop, reload and restart without resurrecting compiled history. Interrupted runs keep their native anchor or conservatively retain available context. Uncheckpointed requests and interrupted boundary continuations survive idle Stop/reload even without a specification; successful bootstrap releases the extra context. Completed idle Stop stays bounded.
- `Awaited activation and restoration`: Startup/tree/fork/auto-start and fenced reload await owned selection. Start activates current same-session memory without claiming expired history. Restoration, auto-start initialization and fork copying survive Stop and cancelled Start waiters; their acceptance applies passive policy and permits configured passive patching. Selection/shutdown still revoke stale work. Acceptance installs memory; late failures never roll it back. Active Start is inert.
- `Awaited fail-operational Stop`: Local policy and passive context switch before cancelable publication waiting. Runtime-only acceptance preserves semantic/provenance files; repeats share the wait. Selection/shutdown/successful Start cancel obsolete work. Failed writes retain cached memory/context and a native fence until accepted Start. Telegram acknowledges early, drops stale results and keeps legacy ports. Forks inherit policy, not fences; fenced reload stays read-only.
- `Compact protocol and diagnostics`: Deduplicates injected plane, scope, response, stewardship and provenance rules without changing tools or memory semantics. Short errors retain operation, scope/path suffix and cause across tools, lifecycle, status and Telegram. Nested/aggregate causes survive transport; operand-first elision preserves Unicode and apostrophes. Opt-in logs retain full targets/input; failed Start emits one notice and tool headings keep a blank line.
- `Awaited memory transactions`: Patches preserve independent shared fields and acceptance order; repeats add no revisions. Setup/cards/evidence accept together under cancelable exclusion/CAS. Preparation/maintenance accept at native `context` or abort inference; runtime-only writes preserve history/provenance. Restore/fork await exact private authority over live shared streams; duplicate/competing Skill writes preserve ownership. Rejected drafts never install; private/selection fences remain.
- `Awaited response acceptance`: Final answers wait cancelably for current shared memory and publish response plus completed-run lifecycle together. Failed publication installs no draft or shared adoption. Native Abort, Stop, selection/run changes, shutdown and superseding answers withdraw obsolete waits without erasing newer work or write fences. Independent-process Pi tests prove waits beyond two seconds, private isolation, next-provider visibility and retained unfinished runs on cancellation.
- `Awaited inspection`: Telegram and continuation readers await coherent cohorts without publication or private substitution. Telegram pairs state/revisions, revokes stale receipts and keeps legacy ports; callbacks acknowledge early and escape late errors. Library inspection APIs now return Promises: callers must await results. Six legacy runtime adapters remain. Read-only current-memory recovery preserves private authority without enabling writes. Missing/invalid evidence never initializes memory.
- `Awaited backup capture`: Backup and canonical mutexes wait cancelably, capture one cohort and preserve replacement owners. Git runs outside canonical exclusion; branch/head drift is rechecked. Settlement awaits completion and shutdown cancels pending reads. Pi 0.87 lacks a settlement Abort signal, so contended backup explicitly defers instead of waiting uninterruptibly. Accepted memory/Stop fences survive; native and independent-writer tests cover ownership, cancellation and coherent commits.

## 0.18.1: Backup Reliability

- `Push lifecycle`: Bounds backup replication to one in-flight push per repository, skips overlap until a later accepted turn, and awaits process closure at session shutdown under the existing push timeout. Suppresses failure reporting after shutdown starts; test fixtures settle pushes before cleanup. Canonical acceptance stays independent of Git replication.
- `Push diagnostics`: Repeated asynchronous push failures produce one concise warning per failure streak until a successful push. Available redacted Git errors are recorded locally even without general logging; an unavailable diagnostic log falls back to one warning with the failure detail. Canonical acceptance and later-turn retry are unchanged.
- `Prompt-prefix evidence`: Version 3 synthetic benchmark reports each inference's serialized context size and within-run shared byte prefix, accepted patch barriers, and matching native user/specification value sizes for State Flow and native Pi, including isolated resume probes. A source-bound local sample and regression coverage inform a later projection decision without changing 0.18.1 model behavior.

## 0.18.0: Independent Revisions and Replicated Backups

- `Independent scope revisions`: Persists independent Global, CWD and Session semantic counters. Each materially changed scope advances once per atomic cohort; no-ops advance none, Session owns response changes, folding preserves counts, and pre-revision 0.17 stores start from retained-tail evidence. Effective uses the truthful `G#/C#/S#` vector rather than a scalar observer count. Metadata v2 keeps v1 readable and fences older writers after a revision-aware scope write.
- `Passive status semantics`: Active terminal status renders `state-flow G#/C#/S#`, while Telegram retains its `State Flow: G#/C#/S#` label format; passive terminal status is absent and Telegram shows `State Flow: off`. Owner Rich snapshots show `#revision`, Effective shows the vector, and read-only inspection may refresh foreign Global/CWD revisions in memory without publication.
- `Response ownership`: Documents response as runtime-owned Session state. Global/CWD retain only the empty structural slot required by the uniform canonical shape and omit it from Telegram Rich views; Effective inherits the Session response.
- `Revision status freshness`: Refreshes terminal status immediately after automatic missing-artifact reconciliation, so an independently advanced Global/CWD revision is visible before any later `patch_state` call rather than appearing to have been caused by that call.
- `Progressive backup replication`: After each successful settled-turn backup attempt, asynchronously pushes the exact current commit without force to the attached branch's explicitly configured remote/ref. Push failure remains visible but cannot affect canonical acceptance or the answer; a later accepted turn retries the latest backup. No durable queue, worker, lease, retry generation, remote policy metadata or semantic Git authority returns.
- `Empty response finalization`: Accepts an ordinary completion with no text as a valid lifecycle boundary, stores the Session response as `""`, and preserves any preceding `patch_state` transition instead of emitting a blocking recovery error.

## 0.17.4: scoped Skill acquisition and passive observability hotfix

- `Passive observability`: Keeps the `state-flow #N` counter visible in terminal and Telegram surfaces while active mode is off, with accepted passive patches advancing the same counter. Telegram scope controls now explicitly retain global/CWD/session/effective inspection in either mode and can lazily read existing shared canonical state when passive model tools are disabled, without initializing or mutating storage.
- `Skill Acquisition AX`: Recognizes only exact registered Pi Skills through public command source metadata and maps user/project/temporary ownership to global/CWD/session artifacts. Matching source hashes need no update; other reads receive one precise optional target hint. Uncompiled reads remain volatile and never block unrelated patches, while attempted compilation retains strict shape, hashing, provenance and CAS validation.

## 0.17.3: passive shared-memory concurrency

- `Passive concurrency`: First passive semantic or compilation-evidence writes now adopt untouched global/CWD updates made by another session after memory was loaded. Targeted shared-scope changes still reject stale writes with scope-specific diagnostics, and competing private-session writes remain fenced. No automatic patch replay, episode activation, storage-format change or weaker publication CAS is introduced.

## 0.17.2: incremental memory model documentation

- `README`: Explains the combination of durable state between user runs and native working context within each run. Clarifies global/CWD/session composition into effective memory, configurable historical access and optional Git backups, with a simpler flow diagram and a compact semantic-plane reference. Runtime behavior is unchanged.

## 0.17.1: precise patch diagnostics and clearer onboarding

- `Patch diagnostics`: Unknown scope-patch keys are reported by their exact JSON-quoted name, with permitted fields listed in intent-first order: intents, contract, working, artifacts, lazy. Accepted patch structure and runtime-owned response protection are unchanged. Thanks to @Jipok for the feedback in #5.
- `README`: Rebuilds the introduction around intent-first memory, explicit scope ownership, small patches and precise reads. Clarifies opt-in active versus default passive behavior, file-authoritative persistence, optional Git backup and the 0.17 format boundary without promising token savings or automatic migration.

## 0.17.0: canonical memory and native Pi integration

- `Pi 0.87 integration`: Aligns SDK pins and lockfile. Native sections compose with companion hooks and refresh on in-run mode changes; context edits and image profiles remain SDK-owned. User anchors survive normalization, steering and in-run Start/Stop; uncertain boundaries retain available summaries/tools without restoring omitted input. Owned compaction keeps the complete accepted run, skips foreign prefixes and awaits completion/refusal before deferred follow-ups. Native trace remains intact.
- `Canonical files and backup`: Removes Git semantic authority, workers and remote push policy. Canonical acceptance stays independent of backup. Settled backup captures owned regular files under a short lock, then stages a coherent snapshot through a temporary worktree/index outside that lock. Ignore/filter policy and unrelated index/worktree data survive; unchanged trees skip. Slow or failed Git cannot undo acceptance or lock out independent canonical writers.
- `Retained scope lifecycle`: Uses historyLimit 0..100 (default 7) for folding, reads and selection; reductions preserve current state and increases never recreate discarded history. Restore/fork binds session lineage beside live shared scopes; selected failures never fall through and Start retries them. Lifecycle-only writes adopt unrelated shared drift without semantic/provenance writes or counter changes. Pre-runtime Stop records only a disabled Pi checkpoint; accepted Stop freezes its handoff.
- `Artifact ownership`: Inspects only exact registered sources; status remains observational. Public and Pi acquisition share fingerprint/compiler classification, including signed mtimes and unavailable evidence without semantic loss. Stable reads compile into the reported scope under CAS with runtime-only provenance/hints; Skills retain actual source hashing. Restore/fork drops unproven future session provenance while preserving semantics, untouched evidence and current shared provenance.
- `Direct completion`: Removes final:true, terminal eligibility, fallback turns, compatibility normalization, private-validation filtering and handshake diagnostics. Material patch_state remains an inference barrier; ordinary accepted answers reconcile at turn_end. Native turn/settle continuations retain memory after the completed specification is removed, without resurrecting prompts, inventing user runs or adding a continuation controller.
- `Intent-first memory`: Preserves intents, contract, working, artifacts, response, lazy ordering in model/presentation surfaces. Every canonical scope requires an object-root lazy plane; progressive reads retain bodies while baseline projection omits them. Owned-draft COW reduces repeated deep copying without changing mutable-result isolation, canonical files or CAS. This does not promise lower heap use, serialization cost or end-to-end latency.
- `Explicit stewardship`: Dedicated cleanup/scope audits require an explicit request. Guidance distinguishes transient specifications from scoped durable contracts, retires inactive intents and preserves consequential uncertainty. Intra-store moves are atomic; external transfers require verified destination acceptance before source deletion. Removes reserved memory_promotions/status handling; promotion-shaped values remain ordinary user data, not a transfer protocol.
- `Breaking format cleanup`: Deletes storage-layout conversion and the exported legacy Skill converter with its fabricated fallback hashes; contract.compiled_skills remains rejected. Predecessor checkpoint/tail envelopes, combined metadata, pre-intents or missing-lazy state, legacy paths and semantic Pi snapshots fail unsupported without rewriting bytes. Current Skill acquisition still hashes executed source bytes.

## 0.16.3: Passive guidance and compatibility cleanup

- `Passive finalization guidance`: Makes the always-available `patch_state` tool contract mode-aware, requiring `final:true` only for active episodes and explicitly forbidding final-only calls in passive turns so tool-level guidance no longer contradicts passive runtime context.
- `Pi compatibility range`: Declares `0.84.4` as the minimum Pi SDK version without an upper peer-dependency bound, replaces stale candidate reports and historical run internals with a concise tested-stack contract, and removes dead legacy test scaffolding plus retired HTML-envelope fixtures without dropping supported storage migrations or current negative-boundary coverage.

## 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`.