@llblab/pi-kit 0.18.1 → 0.19.0

package/CHANGELOG.md

@@ -2,6 +2,18 @@
 
 All notable changes to `@llblab/pi-kit` are documented here.
 
+## 0.19.0 - 2026-09-23
+
+- `Incremental State Flow`: Advances the exact State Flow pin to `0.17.2`, carrying durable scoped memory between user runs while retaining Pi's native working trajectory within each run. Includes bounded historical reads, ordinary answer completion without a separate finalization loop, precise unknown-key diagnostics, and the revised README.
+- `Persistence And Compatibility`: Canonical files now own accepted state; optional Git backup failure cannot reject or roll back an accepted update. Requires Pi `0.87.0+`; State Flow's 0.17 storage format has no in-place predecessor converter. Preserve existing stores and follow the owning package's storage guidance before upgrading.
+- `Package Cohort`: Keeps every other bundled package at its current exact version; the package set, resource inventory, and explicit load order remain unchanged.
+
+## 0.18.2 - 2026-09-22
+
+- `Telegram Operational Hotfixes`: Advances the exact Telegram pin to `0.50.1`, restoring follower registration when canonical Workspace binding deduplication changes a provisional slot and letting the busy leader permanently skip queued Guest prompts while visually clearing their inline placeholders.
+- `Lifecycle And Command Safety`: Adds one-use authorization to armed internal lifecycle actions, prevents Thread naming from Pi commands, and aligns concise autocomplete hints with Pi's argument-first style.
+- `Package Cohort`: Keeps every other bundled package at its current exact version; the package set, resource inventory, and explicit load order remain unchanged.
+
 ## 0.18.1 - 2026-09-20
 
 - `Passive State Flow Guidance`: Advances the exact State Flow pin to `0.16.3`, requiring finalization barriers only in active episodes while preventing gratuitous final-only patches during passive memory use.

package/README.md

@@ -14,14 +14,16 @@ Package links lead to the owning repositories for usage, documentation, issues,
 | [`@llblab/pi-clean-room`](https://github.com/llblab/pi-clean-room) | `0.1.1` | Isolated nested Pi TUI with explicitly selected extensions |
 | [`@llblab/pi-codex-usage`](https://github.com/llblab/pi-codex-usage) | `0.10.0` | Compact Codex/Spark subscription-limit and Business credit-usage status |
 | [`@llblab/pi-grow-loop`](https://github.com/llblab/pi-grow-loop) | `0.8.1` | Visible continuation scheduling and bounded worker Skills |
-| [`@llblab/pi-state-flow`](https://github.com/llblab/pi-state-flow) | `0.16.3` | Incremental scoped state/context/memory compiler with mode-aware passive guidance, proportional operational guidance, intentional agency, reactive dangling-reference diagnostics, safe compaction, and exact publication |
-| [`@llblab/pi-telegram`](https://github.com/llblab/pi-telegram) | `0.50.0` | Telegram companion with native fresh-session replacement, a guarded internal lifecycle gateway, buffered thinking cadence, adaptive Thread continuity, exact queues, files, voice, controls, and Generative Apps guidance |
+| [`@llblab/pi-state-flow`](https://github.com/llblab/pi-state-flow) | `0.17.2` | Incremental scoped context/memory compiler with canonical file persistence, optional Git backups, native working context within each run, and targeted historical reads |
+| [`@llblab/pi-telegram`](https://github.com/llblab/pi-telegram) | `0.50.1` | Telegram companion with guarded lifecycle actions, recoverable Workspace slots, immediate Guest queue Skip, concise Pi command hints, adaptive Thread continuity, exact queues, files, voice, controls, and Generative Apps guidance |
 | [`@llblab/skills`](https://github.com/llblab/skills) | `1.15.0` | Portable workflows for engineering, review, design, context maintenance, and other focused tasks |
 
 Versions are exact by design. An upstream release does not change an installed kit until this repository explicitly advances the dependency and publishes a new kit version. Runtime defects and package-specific feature requests belong in the linked repository; package selection and kit installation issues belong here.
 
 ## Install
 
+Requires **Pi 0.87.0+** and **Node.js 22.19.0+**. State Flow 0.17 introduces a breaking storage-format boundary with no in-place predecessor converter. Preserve existing State Flow stores and review the [owning package's storage guidance](https://github.com/llblab/pi-state-flow/blob/v0.17.2/docs/usage.md#moving-a-store-and-the-017-format-boundary) before upgrading from an earlier kit.
+
 From npm:
 
 ```bash

package/node_modules/@llblab/pi-state-flow/AGENTS.md

@@ -2,52 +2,50 @@
 
 - Keep independent domain modules under `lib/`, mirror every domain with a same-named file under `tests/`, place cross-domain architecture checks in `tests/invariants.test.ts`, and keep `index.ts` as a minimal public-export boundary. Keep `lib/extension.ts` as the Pi lifecycle composition root: it may wire configuration, domain capabilities, handlers, and event subscriptions, but low-level parsing, traversal, formatting, persistence, queue/worker mechanics, and diagnostic I/O belong to their existing owning domains.
 - Keep the extension opt-in and preserve clear attribution to SKILL.state wherever the inherited explicit-state approach is described.
-- Preserve Pi's native tool loop and complete inspectable session trace; project completed-run history only at user-run boundaries. The runtime-context builder owns model projection of the raw scope overlay; callers must not pre-project it. Retain persistent and current-run context-bearing custom messages from other extensions, plus the complete current-run trajectory, except State Flow's own validation feedback when it is represented separately.
-- Expose one canonical materialized state shape across global, CWD, and session scopes with exactly `artifacts`, `contract`, `working`, `intents`, and `response`, plus optional `lazy`; the first four are flexible semantic objects and `response` is the latest complete user-facing answer string where applicable. `intents` contains only active commitments to future action, remains hot by default, and must not become a planner, scheduler, task manager, or execution loop.
-- Key artifacts directly by their source path. Model-visible artifact entries require only a non-empty `description` plus optional forward-compatible metadata; runtime-owned freshness evidence (`sourceHash`, `compilerRevision`, `compiledAt`) belongs in the scope `meta.json` provenance registry, never in projected semantic state. Retired embedded `hash`/`compiler`/`compiled_at` fields remain readable compatibility evidence and are stripped from model projection. Validate provenance restrictions on every authored artifact entry, not on retained legacy state: individual runtime/legacy provenance fields cannot be set or deleted by model patches in any scope.
-- After local activation and before the next enabled inference, discover regular lowercase `*.md` files recursively beneath the configured Knowledge repository root; use canonical absolute paths, hash opaque source bytes and retain their byte counts without decoding or retaining bodies, skip symlinks, and never traverse outside that canonical root. Treat the current candidate set plus explicit owner-confirmed removals as generic global artifact input without invoking Knowledge validators. Partial candidate sets, unavailable roots, and symlink/external/non-Markdown paths never authorize deletion. Re-derive removals from the retained global registry so status inspection and restart cannot consume uncommitted observations; unavailable roots mean unknown freshness. Materialize removals deterministically as runtime-owned global transitions without rereading missing bodies or requesting model compiler output. Never reserve Knowledge document names, provide built-in Knowledge templates, or implement `save_knowledge`.
-- Derive artifact freshness per available evidence: a new source always requires compilation, a matching `sourceHash` or `compilerRevision` detects its own change, malformed present evidence fails closed for the capability that depends on it, and missing evidence degrades to an unknown-but-usable artifact rather than corrupt state or a migration. Never treat `compiled_at` as a correctness signal. Plan acquisition from path/hash identity without source bodies, project stale global candidates as runtime-owned `artifact_invalidations` containing only `{path, reason}`, and publish accepted compilation semantics plus matching provenance in one durable cohort.
-- Correlate successful exact-path reads with the current ordinary global invalidation plan. Require each acquired stale source to have a compact compiler output at the same path in a global transition, reject model-authored provenance fields, and record the runtime-observed source hash plus current ordinary compiler revision in the global provenance registry. Compile routing descriptions by default, never raw Markdown or a full-file summary; preserve uncertainty and reserve richer compilations for reusable operational semantics.
-- Apply one materialized-first acquisition policy to every source: read only for a concrete relevant gap not covered by a sufficient compilation, an exact-source operation including edits, evidenced invalidation, contradiction/failure reconciliation, explicit request, or selection by bounded maintenance. New sessions, routine recall or activation, reassurance, and an index or description alone are not reasons to read. Changed hashes require rereading; prefer the smallest sufficient read.
-- Keep artifact maintenance opt-in, low-frequency, and side-effect free until a selected source is acquired. Select only otherwise-fresh artifacts old enough for maintenance, rank missing/unparseable `compiled_at` first then oldest timestamp and path, and enforce strict per-cycle read-count and source-byte ceilings. Treat source bytes as the conservative source-token upper bound. Never let maintenance displace correctness invalidation; use explicit invalidation refresh for full rebuilds and never mutate source files.
-- Load optional repository-global `config.json` from the canonical `<agentDir>/state-flow/` root once per extension load/reload. `autoStart` defaults false for genuinely new sessions, `passiveBootstrap` and `passiveTools` default true and remain independent of episode lifecycle, `showSuccessfulPatches` defaults true for interactive successful-call JSON rendering, and `remotePublication` selects `off`, `turn-end`, or compatibility `transition`; SDK embeddings may explicitly override the repository. State Flow always owns durable memory while enabled and global semantic memory is always available; these are invariants, not configuration switches. Keep global operator configuration, runtime configuration, and provenance outside model-patchable semantic state.
-- Keep runtime configuration and provenance separate from model-patchable semantic state. Persist session `config.json` for enablement/projection settings, session `runtime.json` for lineage, counters, branch identity, durable base, publication, and migration metadata, and every scope's adjacent `meta.json` for temporal boundaries, ownership where applicable, and artifact provenance. None participates in scope overlay. Read the predecessor combined session `meta.json` only as migration input; the next normal CAS publication must write `runtime.json` and clean known runtime fields from semantic metadata. New Pi checkpoints contain only a durable revision pointer, or `{disabled:true}` when no durable runtime exists on that branch. Preserve exact Git hashes for Git-backed revisions and give file-only current-cohort references an unambiguous distinct identity; file references use `file:<64 lowercase hex>`, bind the store root and complete scoped/runtime cohort, and must not pretend to provide arbitrary cold or branch history. Operationally unavailable references (including expired file cohorts, missing Git, and publication exclusion) retain selection rather than falling through to older disabled markers; malformed immutable targets remain a distinct recovery case; they are not a parallel authoritative semantic or config/meta store. Emit a disabled marker only from proven pre-runtime branch provenance; missing/invalid revisions and failed restoration do not establish that permission. Predecessor checkpoint/tail envelopes are read-only migration input, recognized only by their complete exact structure and converted explicitly through the normal lock/CAS publication path. Validate immutable pointer targets before acquiring the live publication basis; transient publication failures preserve the selected retry reference rather than choosing older semantic state. In Git mode, runtime `revision: "self"` resolves to the commit owning the config/meta pair, not an unrelated later repository commit. File publication uses explicit `publication: "files"` provenance and resolves the exact complete live cohort instead of claiming a Git owner. Use a distinct `meta.temporalRevision` when a runtime-only write selects older semantic scopes; restore their artifact provenance from that same revision and preserve live shared checkpoints, tails, and provenance during session config/meta writes. Persist publication intent as unconfirmed before pushing; reconcile that exact existing commit after restart rather than embedding an impossible self-hash or inventing semantic history.
+- Preserve Pi's native tool loop and complete inspectable session trace; project completed-run history only at user-run boundaries. The runtime-context builder owns model projection of the raw scope overlay; callers must not pre-project it. Retain persistent and current-run context-bearing custom messages from other extensions, plus the complete current-run trajectory. Select a unique captured native user timestamp independently of text decoration, including SDK image hints. Observe native user events even while disabled; Start/Stop must retain that observed run anchor. Reset it at native before-agent-start and session-start/tree boundaries, not semantic mode changes. Observation alone never enables state, publishes memory or authorizes compaction. Without a capture, a unique exact specification match may select only model projection. Missing, nonfinite or ambiguous matches retain available context; projection must never assign the lifecycle run anchor. Direct completion persists no private validation feedback.
+- Expose one canonical intent-first materialized state shape across global, CWD, and session scopes with exactly `intents`, `contract`, `working`, `artifacts`, `response`, and `lazy`; the first four and the required `lazy` root are flexible semantic objects, while `response` is the latest complete user-facing answer string where applicable. Only model baseline projection omits lazy bodies. Preserve this plane order in model-facing projection and state presentation. `intents` contains only active commitments to future action, remains hot by default, and must not become a planner, scheduler, task manager, or execution loop.
+- Key artifacts directly by their source path. Model-visible artifact entries require only a non-empty `description` plus optional forward-compatible metadata; runtime-owned compilation evidence (`sourceFingerprint`, `sourceHash`, `compilerRevision`, `compiledAt`) belongs in the scope `meta.json` provenance registry. Reserve model-authored `hint`; runtime may add it only to effective/model projection and never to canonical scope state. Retired embedded `hash`/`compiler`/`compiled_at` fields remain readable compatibility evidence and are stripped from model projection. Validate provenance restrictions on every authored artifact entry, not on retained legacy state: individual runtime/legacy provenance fields cannot be set or deleted by model patches in any scope.
+- Inspect only exact artifact source paths already registered in global, CWD, or session state. Never scan directories, discover files, reserve a Knowledge root, interpret file extensions, or read unrelated source bodies. Observe regular non-symlink files through `size + mtimeNs`; proven absence removes the artifact and provenance from each exact owning scope, while relative, symlink, directory, inaccessible, or otherwise unavailable paths are non-destructive evidence.
+- Use `classifyArtifactCompilationNeed` for public acquisition/rehydration and ordinary-artifact Pi invalidations. Compare observed fingerprints with hidden provenance; missing/malformed retained fingerprints, malformed compiler evidence, and compiler changes request compilation without declaring semantic corruption. Fingerprint-only decisions ignore unused legacy hashes, while explicit current hashes retain their checks; never invent hashes in read plans. Accept signed filesystem `mtimeNs`, including pre-epoch sources. Preserve changed-source semantics and add `hint` only to model projection. Effective Skill entries mask lower ordinary entries and retain their separate hash protocol.
+- Correlate successful exact-path reads with the current registered-artifact invalidation plan. Accept compilation only when the fingerprint remains stable before and after acquisition and at final publication, then store the accepted fingerprint with current compiler revision in the owning scope's provenance under scope causal-basis CAS. Runtime/Skill guidance and rejection text must identify that exact reported scope and path, never direct an existing CWD/session artifact to global. Generic artifact maintenance never calculates content hashes; retained `sourceHash` is transitional compatibility evidence only. Restore/fork preserves current shared provenance, but drops session provenance for each artifact path touched by any retained session patch after the selected boundary, including change-away-and-back. Keep the selected semantic value usable with unavailable compilation evidence; untouched paths and current-head selections retain their proven evidence.
+- Load optional repository-global `config.json` from the canonical `<agentDir>/state-flow/` root once per extension load/reload. `autoStart` defaults false for genuinely new sessions, `passiveBootstrap` and `passiveTools` default true and remain independent of episode lifecycle, `showSuccessfulPatches` defaults true for interactive successful-call JSON rendering, and `historyLimit` defaults to 7 and accepts integers from 0 through 100. SDK embeddings may explicitly override the repository. State Flow always owns durable memory while enabled and global semantic memory is always available; these are invariants, not configuration switches. Keep global operator configuration, runtime configuration, and provenance outside model-patchable semantic state.
+- Keep runtime configuration and provenance separate from model-patchable semantic state. Persist session `config.json` for enablement/projection settings, session `runtime.json` for lineage, counters, and branch identity, and every scope's adjacent `meta.json` for temporal boundaries, ownership where applicable, and artifact provenance. None participates in scope overlay; predecessor combined metadata and checkpoint envelopes are unsupported. Pi checkpoints contain only a retained semantic boundary with lifecycle fields, or `{disabled:true}` from proven pre-runtime branch provenance. Before retained selection or origin adoption, bind the session stream's checkpoint/tail identities to its runtime lineage; a position alone never proves ownership. Permit sparse session records and proven inherited pre-origin streams. Global/CWD streams remain live and are validated independently, not against another session's historical lineage; continuation inspection follows the same ownership rule. Expired, contradictory, or revision-pointer targets fail closed without falling through. Session runtime metadata contains no storage receipt, Git identity, temporal revision pointer, publication mode, or push intent.
 - Overlay materialized state recursively in `global → cwd → session` order. Scope-local deletion removes only that scope's key so a lower-scope value becomes visible again; scope never changes instruction authority. Route branch/run-local continuation to session, project-local reusable state and Skill artifacts to CWD, and cross-project reusable state to global.
-- Reserve `state` for the runtime materialized semantic view. `checkpoint.json` contains only the canonical materialized semantic state, each nonblank `patches.jsonl` line contains only one semantic patch, and adjacent `meta.json` owns their checkpoint/tail boundaries plus CWD identity. For each scope, current state is exactly `materialize(checkpoint.json, patches.jsonl, meta.json)`: an older anchored checkpoint plus its ordered tail of at most seven materially effective semantic patches. On overflow, apply the oldest patch into the checkpoint, advance its `through` boundary, remove it, and append the new patch. Never truncate unapplied replay records or replay patches over an already-current snapshot.
-- Give every accepted semantic transition one opaque identity shared by all affected scope records, with explicit active causal lineage. A branch-local position can order identities but never acts as a global counter, substitutes for identity, or merges forks. Unchanged scopes contribute no record and remain unchanged at that boundary. Adopt revision-proven inherited streams at a new session origin without rewriting their checkpoints/tails; pre-origin coordinates are not one shared clock. A restored branch adopts current proven live shared streams it does not modify at a fresh origin while preserving its selected session layer; a shared scope the accepted transition actually changes must still match its selected basis or fail closed naming that scope. Reconciliation adoption is not a fabricated semantic transition, parent link, or retry loop. True semantic no-ops and origin adoption do not advance semantic history.
-- Define `effective[n]`, `global[n]`, `cwd[n]`, and `session[n]` at the same nth previous accepted transition boundary in the active lineage, never the nth local patch of each scope. Guarantee offsets zero through seven once the lineage has seven proven transitions; report earlier-than-origin history as unavailable for new/migrated lineages and reject offsets beyond seven on the hot interface. Reconstruct scopes at one target before overlaying them.
-- Keep historical reads lazy through the smallest runtime/model read interface. Normal inference gets only current effective state and useful bounded compact transition context, never eight full snapshots. `patch_state` is the sole semantic mutation tool. `read_state` treats unscoped semantic paths as current effective aliases, accepts explicit effective/scoped materializations and scope-local retained accepted patches, and rejects the retired top-level `state` segment; materialization indices share the composed causal lineage while `patches[n]` walks the selected scope's retained patch tail. The public reader accepts only `path` or `paths`; temporal offsets and scope selection are expressed in path syntax. Reads return the exact boundary and never publish, append a checkpoint, or advance history. Both tools follow branch enablement and host tool restrictions; the patch barrier blocks reader siblings too. Live/cached checkpoint plus tails own the hot path; use Git for branch restoration and explicit cold inspection, not to rebuild current state on every inference.
-- Store runtime state in its own directory with optional Git durability, defaulting to `state-flow/` beneath Pi's configured agent directory (`~/.pi/agent/state-flow/` normally), independently from the Knowledge Markdown source root. Use exactly these owned paths: `checkpoint.json`, `patches.jsonl`, and `meta.json` for global; `<cwd-key>/checkpoint.json`, `<cwd-key>/patches.jsonl`, and `<cwd-key>/meta.json` for CWD; `<cwd-key>/<session-key>/checkpoint.json`, `patches.jsonl`, `meta.json`, `config.json`, and `runtime.json` for session. Do not create `.state-flow`, `scopes`, or another storage/history namespace. Mirror Pi's native CWD session-directory encoding and JSONL-basename session key (deriving `<header timestamp>_<UUID>` for in-memory sessions), while retaining separately verifiable canonical identity provenance in owned state. Keep the UUID authoritative, reject unsafe segments and mismatches rather than selecting another scope, and use CWD `meta.json` ownership to fail closed on Pi-name collisions.
+- Reserve `state` for the runtime materialized semantic view. `checkpoint.json` contains only the canonical materialized semantic state, each nonblank `patches.jsonl` line contains only one semantic patch, and adjacent `meta.json` owns their checkpoint/tail boundaries plus CWD identity. For each scope, current state is exactly `materialize(checkpoint.json, patches.jsonl, meta.json)`: an older anchored checkpoint plus its ordered tail of at most the configured `historyLimit` materially effective semantic patches. On overflow, apply the oldest patch into the checkpoint, advance its `through` boundary, remove it, and append the new patch. Never truncate unapplied replay records or replay patches over an already-current snapshot. Decode valid persisted retention against the format maximum before enforcing a smaller operator limit: restrict boundary selection to the configured window, then fold excess scope tails during canonical origin acceptance, including fork. Preserve current shared values/provenance and selected private state; raising the limit never reconstructs discarded history.
+- Give every accepted semantic transition one opaque identity shared by all affected scope records, with explicit active causal lineage. A branch-local position can order identities but never acts as a global counter, substitutes for identity, or merges forks. Unchanged scopes contribute no record and remain unchanged at that boundary. Adopt proven inherited streams at a new session origin without rewriting their checkpoints/tails except for configured retention folding; pre-origin coordinates are not one shared clock. A restored branch adopts current proven live shared streams it does not modify at a fresh origin while preserving its selected session layer; a shared scope the accepted transition actually changes must still match its selected basis or fail closed naming that scope. Reconciliation adoption is not a fabricated semantic transition, parent link, or retry loop. True semantic no-ops and origin adoption do not advance semantic history.
+- Define `effective[n]`, `global[n]`, `cwd[n]`, and `session[n]` at the same nth previous accepted transition boundary in the active lineage, never the nth local patch of each scope. Guarantee offsets zero through the configured `historyLimit` once the lineage has enough proven transitions; report earlier-than-origin history as unavailable and reject offsets beyond that configured hot-history bound. Reconstruct scopes at one target before overlaying them.
+- Keep historical reads lazy through the smallest runtime/model read interface. Normal inference gets only current effective state and useful bounded compact transition context, never an eager window of full snapshots. `patch_state` is the sole semantic mutation tool. `read_state` treats unscoped semantic paths as current effective aliases, accepts explicit effective/scoped materializations and scope-local retained accepted patches, and rejects the retired top-level `state` segment; materialization indices share the composed causal lineage while `patches[n]` walks the selected scope's retained patch tail, with both paths enforcing the same configured `historyLimit`. The public reader accepts only `path` or `paths`; temporal offsets and scope selection are expressed in path syntax. Reads return the exact retained boundary and never publish, append a checkpoint, or advance history. Both tools follow branch enablement and host tool restrictions; the patch barrier blocks reader siblings too. Canonical checkpoint plus tails own current and retained history; never use Git as semantic read authority.
+- Store runtime state in its own directory with optional Git backup, defaulting to `state-flow/` beneath Pi's configured agent directory (`~/.pi/agent/state-flow/` normally), independently from optional registered artifact sources. Use exactly these owned paths: `checkpoint.json`, `patches.jsonl`, and `meta.json` for global; `<cwd-key>/checkpoint.json`, `<cwd-key>/patches.jsonl`, and `<cwd-key>/meta.json` for CWD; `<cwd-key>/<session-key>/checkpoint.json`, `patches.jsonl`, `meta.json`, `config.json`, and `runtime.json` for session. Do not create `.state-flow`, `scopes`, or another storage/history namespace. Mirror Pi's native CWD session-directory encoding and JSONL-basename session key (deriving `<header timestamp>_<UUID>` for in-memory sessions), while retaining separately verifiable canonical identity provenance in owned state. Keep the UUID authoritative, reject unsafe segments and mismatches rather than selecting another scope, and use CWD `meta.json` ownership to fail closed on Pi-name collisions.
 - Classify every filesystem cohort before recovery: complete valid evidence is usable; total absence is recoverable only from an explicit semantic default or exact surviving authority; partial, malformed, contradictory, or authority-losing evidence fails closed at the smallest dependent capability. A wholly absent untouched global/CWD checkpoint-tail pair is current empty shared reality and must not resurrect selected cold values; a patch targeting that disappeared scope is stale and must fail for reinference. Missing provenance means unavailable freshness, not semantic corruption. Perform every repair through normal locked/CAS publication, never ad-hoc writes.
-- Support the release-owned storage migration chain through the migration domain: complete predecessor checkpoint/tail envelopes convert into semantic-only checkpoint/tail files plus temporal `meta.json`, the 0.13 → 0.14 step splits every owner-proven session's combined `meta.json` into scope-only `meta.json` plus branch/run `runtime.json`; and the 0.14 → 0.15 step adds empty `intents` to retained semantic checkpoints without inferring commitments. Execute the applicable steps through one normal locked/CAS publication. Replace a Git-backed semantic-envelope store's history with one new root commit for the complete migrated tree; apply the same cohort without Git in file-only mode. `state.json`, pre-0.4 hashed layouts, and semantic Pi checkpoint envelopes are unsupported and never become recovery authority. Exercise migrations in temporary repositories rather than modifying the user's active data during development.
-- Read and write only regular non-symlink State Flow-owned files at those exact paths, publish each file by same-directory atomic rename, preserve arbitrary repository contents, and classify ownership exactly. Git acceptance follows the complete-delta isolated-index contract below. Retain opaque source bytes for file identity and rollback, not decoded-text reconstructions. Use validated structural JSON equality for in-process semantic comparisons; reserve cryptographic hashes for compact identities that cross inference, persistence, process, or source-freshness boundaries. Serialize cooperating Git publications through a common-Git-directory publication lock; low-level file helpers require caller exclusion. Recheck prepared bases before each replacement/deletion and restore only bytes still matching the publisher's own output. Preserve detected concurrent changes and report unresolved rollback conflicts; do not claim kernel-atomic multi-file CAS against nonparticipating writers. Markdown discovery uses its independently configured source root, defaulting to `knowledge/` beneath Pi's agent directory; a storage-root override must not redirect source discovery.
-- At instance initialization resolve the repository, CWD key, and session key; load each scope's anchored checkpoint and tail, materialize at the selected temporal boundary, then overlay `global → cwd → session`. Install cached view and publication basis atomically only after successful restoration/initialization; unavailable publication is an error, not a semantic no-op. Branch recovery may reuse one owner-bound, single-use inspection of the exact selected immutable Git revision, with a detached inspection snapshot and a freshly acquired live publication basis at installation. Revalidate mutable file cohorts, legacy snapshot fallbacks, and redirected runtime owners; never turn inspection into a long-lived revision or publication-basis cache. Preserve the selected revision across transient restore failure so an explicit start can retry it. A genuinely new session gets an empty session layer and inherits only global/CWD values; it must never reuse another same-CWD session layer. Explicit native fork adoption instead follows the [session-copy contract](docs/fork-contract.md): copy the proven source session checkpoint/tail and provenance into a distinct owner over current shared streams, without pruning shared provenance or modifying the parent. Use a fresh origin, preserve copied replay records, reject occupied live/HEAD targets, and publish/checkpoint the child only after CAS acceptance. Inherited parent pointers never authorize an empty reset; fence parent passive Stop projection across child reload.
-- Bind every loaded scope and active Pi branch/checkpoint to the corresponding State Flow Git revision. Resume and tree restoration must recover branch-correct runtime config and semantic layers from that revision without blindly importing Git `HEAD`; reading an older revision must use object-level Git reads and never reset or check out the shared repository worktree.
-- Every accepted semantic change, including session-only and response-only changes, atomically updates affected checkpoint/tail pairs and temporal metadata and creates one immediate local Git commit when Git is available; each commit stages the complete non-ignored worktree delta (`git add -A` semantics, including manual deletions) before overlaying exact prepared State Flow outputs, respects `.gitignore`, keeps State Flow-owned active files under compare-and-swap protection, and synchronizes the caller-visible index to the committed tree. `remotePublication` is branch runtime policy: `turn-end` queues only the newest accepted target for asynchronous non-interactive push, `off` remains local-only, and `transition` preserves synchronous legacy behavior. Queue state is operational metadata beneath the Git common directory, not semantic history; require exact scalar-string commit targets/confirmations without coercion, destination identity, symlink-safe atomic CAS, descendant coalescing with lineage-rewrite recovery that retargets the live commit, cross-process worker leases, restart recovery, and truthful failure diagnostics. Revalidate dead lease ownership under the existing queue writer lock before removal; fresh exclusive creation and live self-PID/token release remain independent of that gate. Preserve malformed and non-regular lease records. Remote failure never rolls back accepted state or regenerates an answer. A repository with no remote is intentionally local-only; only Git executable `ENOENT` authorizes file-only mode.
-- Own asynchronous pushes per extension generation with a 15-second attempt budget and at most two seconds of shutdown waiting. On `session_shutdown`, cancel owned children and permanently fence old-generation queue writes and relaunch. Cancellation or elapsed waiting is not child-exit evidence: keep the lease until exit or proven spawn failure, and warn when cleanup remains unconfirmed. These deadlines govern asynchronous replication, not semantic acceptance or the compatibility synchronous mode.
-- Register `patch_state` as the sole model-authored semantic mutation protocol. Its canonical model-facing grammar accepts optional fixed `global`, `cwd`, and `session` semantic patches plus optional `final:true`; require at least one scope or `final:true`, reject unknown fields, empty supplied scopes, material no-ops, and the retired `{scope, patch}` / `unchanged` grammar. As an unadvertised graceful-degradation layer, normalize only unambiguous Boolean-like `final` primitives before schema validation, treat false-like values as non-terminal intent, and accept a false-only call as an inert no-op without a transition or diagnostic; never apply raw JavaScript truthiness. Validate every supplied scope against one causal basis and publish it all-or-nothing with one identity, temporal boundary, and durable cohort. Never accept model-authored `response`.
-- Treat every semantic `patch_state` as a strict inference barrier. Give it sequential execution mode; find the matching synchronized assistant through public parent traversal from the selected leaf without constructing a full branch during tool preflight; require exactly one `patch_state` call in that response and block every sibling tool call before execution. Every enabled iteration begins terminal-ineligible; only a successful call containing `final:true` latches eligibility for the next accepted `turn_end`, without stopping later reasoning, tools, or patches. If a terminal draft ends before eligibility, preserve it as the runtime-owned response at that `turn_end` and start at most two same-run fallback turns whose only purpose is the `final:true` patch; an eligible draft whose final validation fails after a later acquisition follows the same path. Fallback turns never enter `response`, and their only instruction is to apply `patch_state` with any durable changes and `final:true`, or `{final:true}` alone. A successful fallback closes resolution with the preserved answer intact; two failed fallbacks close the iteration with the preserved answer and current state plus one bounded warning and a finalization diagnostic. Failed patch calls do not consume fallback turns. A subsequent legal patch remains possible, and only an accepted ordinary answer is reconciled.
-- Reconcile `response` only from the actually accepted ordinary assistant answer at `turn_end`; it remains runtime-owned. State Flow has no terminal HTML-comment mutation protocol and does not parse generic service comments. The first terminal draft that cannot be reconciled is preserved as the iteration response rather than discarded; fallback turns during pending resolution never reach `response`. Other extensions retain ownership of their own comments and output handling.
+- Accept only the canonical semantic checkpoint/tail plus temporal metadata and separate session config/runtime contract. Predecessor checkpoint/tail envelopes, combined session metadata, pre-`intents` checkpoints, `state.json`, pre-0.4 hashed layouts, and semantic Pi checkpoint envelopes are unsupported and must fail without rewriting existing bytes. No dedicated migration domain or explicit runtime migration phase exists. Exercise unsupported-format cases only in temporary repositories rather than modifying the user's active data during development.
+- Read and write only regular non-symlink State Flow-owned files at those exact paths, publish each file by same-directory atomic rename, preserve arbitrary repository contents, and classify ownership exactly. Retain opaque source bytes for file identity and rollback, not decoded-text reconstructions. Use validated structural JSON equality for in-process semantic comparisons; reserve cryptographic hashes for compact identities that cross persistence/process boundaries. Serialize cooperating canonical-file writers through file-cohort exclusion and CAS. Recheck prepared bases before each replacement/deletion and restore only bytes still matching the publisher's own output. Preserve detected concurrent changes and report unresolved rollback conflicts; do not claim kernel-atomic multi-file CAS against nonparticipating writers. Inspect only exact already-registered artifact paths; do not discover or own a Knowledge directory.
+- At instance initialization resolve the repository, CWD key, and session key; load each scope's anchored canonical checkpoint and tail, materialize at the selected retained boundary, then overlay `global → cwd → session`. Install cached view and file publication basis atomically only after successful restoration/initialization. Revalidate mutable file cohorts; never turn inspection into a long-lived publication-basis cache. Preserve selected retained-boundary evidence across transient restore failure so explicit Start can retry it. A genuinely new session gets an empty session layer and inherits only global/CWD values; it must never reuse another same-CWD session layer. Explicit native fork adoption follows the [session-copy contract](docs/fork-contract.md): copy the proven retained source-session stream and provenance into a distinct fresh canonical origin over current shared streams, without modifying parent-private files. Reject occupied targets and checkpoint the child only after CAS acceptance. Inherited parent pointers never authorize an empty reset; fence parent passive Stop projection across child reload.
+- Bind active Pi checkpoints to retained semantic boundaries in the current canonical lineage. Resume and tree restoration select only retained private session history while global/CWD scopes remain live; every failure resolving a selected boundary fails closed without falling through to older checkpoints, disabled markers, Git revisions, or unrelated newer private state. Passive shared-memory availability does not prove the selected private layer: preserve the recovery failure, reject session reads and all publication until it is resolved, and let explicit Start retry the exact selection. Never checkpoint a passive substitute over failed branch recovery.
+- Every accepted semantic change, including session-only and response-only changes, atomically updates affected canonical checkpoint/tail pairs and temporal metadata without creating a Git commit. After an accepted turn reconciles its response and reaches `agent_before_settle`, one best-effort backup may commit only State Flow-owned already-written files. Acquire the backup mutex before briefly locking canonical storage for bounded root/CWD/session namespace inventory and regular-file byte capture; canonical writers never acquire the backup mutex. Release the canonical lock before every Git command, filter, staging write, ref update, or index synchronization. Stage only the captured snapshot through a private temporary worktree/index, preserve Git ignore/filter policy, and never inventory artifact sources or unrelated directory trees. Keep unrelated staged/index-only content and worktree edits intact; synchronize only exact owned index paths, include HEAD-owned deletions even when already absent from the caller index, and never create an unowned-only initial backup. Backup failure is diagnostic-only and never rolls back state, suppresses an answer, requests continuation, or blocks a later turn. Durable push queues, publication workers, worker leases, and remote retry generations do not exist.
+- Register `patch_state` as the sole model-authored semantic mutation protocol. Its canonical grammar accepts one or more fixed `global`, `cwd`, and `session` semantic patches; reject unknown fields, empty supplied scopes, material no-ops, and retired finalization or `{scope, patch}` / `unchanged` grammar. Validate every supplied scope against one causal basis and publish it all-or-nothing with one identity, temporal boundary, and durable cohort. Never accept model-authored `response`.
+- Treat every semantic `patch_state` as a strict inference barrier. Give it sequential execution mode; find the matching synchronized assistant through public parent traversal from the selected leaf without constructing a full branch during tool preflight; require exactly one `patch_state` call in that response and block every sibling tool call before execution. The next inference sees rematerialized state. Ordinary accepted answers require no finalization patch or fallback inference.
+- Reconcile `response` only from the actually accepted ordinary assistant answer at `turn_end`; it remains runtime-owned. State Flow has no terminal HTML-comment mutation protocol and does not parse generic service comments. Other extensions retain ownership of their own comments and output handling.
 - Treat terminal state as a decision-relevant handoff, not narration: retain source-addressed reusable operational knowledge in `artifacts`; compile stable requirements, confirmed decisions, rejected approaches, and interface commitments into `contract`; retain observations, validation, failures, current domain state, unresolved work, interaction consequences, and exact continuation in `working`. Preserve relevant completed prerequisites and verified outcomes while removing obsolete progress narration; reconcile only information affected by the run and relevant existing commitments, not every scope or repository surface.
 - Preserve active constraints, unresolved questions, consequential negative results, and the next discriminating check before compression. Distinguish observations, user requirements, assistant decisions, and hypotheses; do not promote assistant conclusions to user requirements. Treat resource, document, memory, Skill, and agent locators as semantic references wherever context expresses them. Inside ordinary strings and prose, encode a semantic-state path as `$` immediately followed by one valid `read_state` path, for example `$effective.lazy.memory[7]`; the prefix distinguishes a reference from incidental path-like text and leaves room for future parsing. `{"$ref":"cwd.lazy.plan"}` remains the optional structured state-reference form; neither form is a runtime link type. External resource locators retain their native path, URI, Skill, or agent syntax. Resolve references explicitly through the appropriate read/tool when needed and infer no authority, existence, dependency, hydration, execution, or completion merely from their presence. Never scan, audit, or proactively resolve references merely to find broken ones. Only after one requested `read_state` value path is missing may the query domain perform one bounded reverse lookup over current model-patchable semantic planes for exact structured `$ref` and `$path` matches. When durable sources match, return a successful top-level `{value:null, hint:[...]}` diagnostic sentinel: every hint has `type:"dangling-reference"`, an action message, and at most three runtime-verified current owning paths. The null sentinel is never presented without `hint` for this case; keys, patch, and multi-path reads retain ordinary all-or-error semantics. Never scan runtime-owned `response`, and retain the ordinary missing-path error when no durable source matches. A match proves durable semantic provenance, not staleness; no match does not prove invention. The agent may then inspect ownership and patch a proven stale source while preserving surrounding meaning. Effective-state absence does not identify ownership, and unavailable history, inaccessible external resources, or transient read failure do not prove a dangling reference. Retain useful source locators and validity conditions for consequential facts without mandatory per-value metadata. Keep rejection reasons and reconsideration conditions. Reconcile contradictions through evidence or user clarification instead of silently overwriting established constraints or observations; retain unresolved conflicts and decision-relevant hypotheses as uncertain. These are protocol obligations, not deterministic semantic validation gates.
 - Treat `working` as last observations, not a live workspace. Revalidate volatile facts before consequential actions; after interruption or branch navigation inspect relevant external effects before repeating operations. Failed state commits and restored memory do not undo tool effects. Missing evidence proves neither success nor absence of effects: retain uncertainty and the next check. Keep revalidation targeted, without action ledgers or runtime freshness/rollback guarantees.
-- Treat each successful `SKILL.md` read as CWD artifact acquisition using the finalized tool-execution arguments after mutable interception: require a non-empty compiler output in the next `patch_state` call under `cwd.artifacts[exactReadPath]` with `description`, `kind: "skill"`, and a flexible non-empty `compilation` object; hash the executed source bytes and record runtime-owned `sourceHash` plus `skill-artifact-v1` `compilerRevision` in the CWD provenance registry; reject missing, unhashable, malformed, or forged freshness data; replace the complete prior Skill artifact and its provenance entry on refresh so obsolete evidence cannot survive. `contract.compiled_skills` is retired and rejected; migrate useful legacy entries into artifacts while preserving behavior and marking fallback hashes unverified when the source is unavailable.
-- Make state stewardship an ordinary model responsibility without a background loop or gratuitous full-state rewrite. Every handoff curates touched and obviously stale or mis-scoped visible branches: place new knowledge at the narrowest valid scope, merge fragmented facts, compress history into conclusions, and delete stale, completed, redundant, or low-value keys while preserving active commitments and evidence. At a completed feature/release/campaign, project switch, or active-version change, require one bounded scoped reconciliation before terminal completion; use targeted `read_state` when ownership is not visible, then write and verify the destination before deleting and verifying the source. Global is only established cross-project/user/environment knowledge, CWD is reusable project truth, and session is branch/run continuation.
-- Accept omitted semantic fields inside each supplied scope patch, but reject empty supplied scopes; when no state change is needed require explicit `{final:true}` without inventing bookkeeping. This final-only call changes only ephemeral terminal eligibility and creates no semantic transition, identity, temporal step, or Git commit. Always require an accepted non-empty answer, which runtime owns as session `response`. A changed response is a semantic transition; identical complete semantic state finalizes lifecycle without a patch, identity, or temporal step. Semantic usefulness and optimization remain protocol-owned because deterministic validation cannot prove them.
-- Agent-level opt-in `logging` appends local JSONL diagnostics for rejected `patch_state` attempts and preserved drafts plus fallback turns while turn resolution remains pending. Every rejected call retains its exact attempted arguments plus the precise error and, when available, tool identity, call id, resolution attempt, and terminal-eligibility state; successful patches are never logged. Preserve exact text blocks only where useful, reduce other blocks to structural identity, never duplicate reasoning bodies, and keep logging outside semantic state, scope metadata, checkpoints, and publication. Logging failure emits at most one warning and never changes resolution, enablement, or accepted state.
+- Treat each successful `SKILL.md` read as CWD artifact acquisition using the finalized tool-execution arguments after mutable interception: require a non-empty compiler output in the next `patch_state` call under `cwd.artifacts[exactReadPath]` with `description`, `kind: "skill"`, and a flexible non-empty `compilation` object; hash the executed source bytes and record runtime-owned `sourceHash` plus `skill-artifact-v1` `compilerRevision` in the CWD provenance registry; reject missing, unhashable, malformed, or forged freshness data; replace the complete prior Skill artifact and its provenance entry on refresh so obsolete evidence cannot survive. `contract.compiled_skills` is retired and rejected; never fabricate fallback hashes or bypass explicit source acquisition.
+- Make state stewardship an ordinary model responsibility without a background loop or gratuitous full-state rewrite. Every handoff curates touched and obviously stale or mis-scoped visible branches: place new knowledge at the narrowest valid scope, merge fragmented facts, compress history into conclusions, and delete stale, completed, redundant, or low-value keys while preserving active commitments and evidence. Dedicated cleanup and scope audits require an explicit user request; a feature/release/project boundary may motivate a recommendation, not an automatic audit. For a proven move within one store, inspect both owners, resolve conflicts, apply destination/source changes through one atomic multi-scope patch, and verify both owners plus the effective overlay. External transfers require destination-native acceptance verification before source deletion. Global is only established cross-project/user/environment knowledge, CWD is reusable project truth, and session is branch/run continuation.
+- Accept omitted semantic fields inside each supplied scope patch, but reject empty supplied scopes and require at least one material semantic or provenance change. When no state change is needed, do not call `patch_state`. Always require an accepted non-empty answer, which runtime owns as session `response`. A changed response is a semantic transition; identical complete semantic state finalizes lifecycle without a patch, identity, or temporal step. Semantic usefulness and optimization remain protocol-owned because deterministic validation cannot prove them.
+- Agent-level opt-in `logging` appends local JSONL diagnostics for rejected `patch_state` attempts and response-finalization failures. Every rejected call retains its exact attempted arguments plus the precise error and, when available, tool identity and call id; successful patches and accepted answers are never logged. Preserve exact text blocks only where useful, reduce other blocks to structural identity, never duplicate reasoning bodies, and keep logging outside semantic state, scope metadata, checkpoints, and publication. Logging failure emits at most one warning and never changes enablement or accepted state.
+- Keep `applyPatch` results and staged mutable drafts detached from caller patches and accepted scopes. Detach once at the public patch boundary; private owned-draft COW may share untouched paths only within that isolated basis. Clone incoming replacements, detach inherited objects before preserving their merge behavior, and retain late-response/artifact mutation isolation. Do not trade CAS, publication rollback or public/historical read isolation for cross-boundary sharing.
 - Recursively materialize patches immediately; empty objects preserve, nested object-key `null` deletes, and `null` anywhere in semantic state including arrays is invalid. This prohibition does not apply to runtime envelopes such as an origin's null parent. Persist runtime-normalized replay patches that exactly reproduce accepted state, including complete artifact replacement; runtime-owned provenance is stored in scope `meta.json` and is not part of semantic replay.
 - Do not impose project schemas, state or patch byte caps, dynamic growth pressure, observation envelopes, action authorization, action ledgers, or state-size limits.
-- Rotate the turn-stable specification on every user-initiated run, while runtime-triggered turn-resolution continuation remains inside that same run. Persist the full specification only while that run is unfinished, then remove it atomically with accepted terminal response reconciliation. Keep user-controlled specification text at user authority: never interpolate it into the system prompt; repeat it only in synthetic user runtime context. Treat materialized state in that message as fallible assistant-produced data whose transport role does not elevate it into user instructions.
-- When enabled inside an existing session, retain Pi's active context for exactly one complete bootstrap run and require its `patch_state` resolution to migrate all future-relevant context.
-- Restore extension state from the active Pi session branch's checkpoint and recorded State Flow revision, not the full session entry list or current Git `HEAD`, on both startup and successful in-session tree navigation.
-- Render compact status as accent `state-flow` plus dim `#<step>`. `/state-flow-status` must distinguish session config/meta from semantic temporal materialization; show the CWD and session keys, step, active temporal head and State Flow revision, available hot-history depth, per-scope artifact/tail counts, discovered global Markdown stale reasons, and pending publication; and render only the effective global → CWD → session materialization as semantic JSON, without reading or dumping source bodies beyond path/hash discovery needed for freshness diagnostics. Distinguish selected retained tail counts from active history depth; inherited tails may predate the origin. When temporal materialization is unavailable, report unknown counts/freshness and unavailable state rather than inventing empty projections.
-- Explicit `/state-flow-start` creates the State Flow directory when missing and returns after locally usable runtime acceptance for normal `turn-end`/`off` policy. If Git is installed, initialize an exact-root Git repository when needed, including a populated file-only store, preserving all existing bytes and unrelated files; an ancestor repository is not a valid substitute. Skip full predecessor-format migration planning only when all exact legacy snapshot names are absent, and defer Markdown freshness discovery until before the next enabled inference. If Git is absent, use file persistence. Manual-mode startup/status/restore do not initialize Git; configured automatic start of a genuinely new session uses the same initialization as explicit start. Never create external accounts, remote repositories, credentials, or remote configuration; those remain operator-owned. Never auto-import, delete, or reset files/history in a previous Knowledge-backed store; old branch revisions require their original Git history to remain available in the selected store. `/state-flow-start` must initialize missing global, CWD, and current-session checkpoint/tail pairs plus session config/meta through compare-and-swap publication when required, enable only the current session branch, and bootstrap prior conversation when needed. Explicit start on a proven pre-runtime branch (no checkpoint or an ordinary-disabled marker) establishes an empty session origin rather than importing a later same-session layer; validate existing runtime identity, retain shared streams unchanged, and preserve later branch data in cold Git history. Ordinary new sessions remain manual unless agent-level `autoStart` is true; CWD materialization alone grants no automatic activation. Configured new sessions may initialize missing CWD state and receive distinct empty session layers while inheriting global/CWD values. Resumed and tree-selected branches restore their own config and temporal lineage, regardless of the global flag.
-- `/state-flow-stop` returns to the configured passive bootstrap/tool combination and must persist only the current session/branch's `config.enabled = false` and necessary runtime provenance, preserving all semantic checkpoints/tails and creating no semantic transition. Retain a frozen handoff plus the active user-run trajectory (including later tool results), post-stop conversation, and foreign context-bearing custom messages across same-physical-session reload/resume/tree. Exclude completed pre-run conversation and private State Flow validation feedback; idle Stop does not retain the completed run. Active restart replaces passive mode but uses that bounded boundary for its one migration run; new and forked physical sessions inherit neither projection. It does not rewrite agent-level `autoStart` or change its policy for future new sessions.
-- After an accepted non-bootstrap run settles with no pending input, State Flow may request native manual compaction under a generation-private marker only when public `getContextUsage()` reports at least 24,000 tokens. Keep the complete latest accepted user iteration, store only revision/step identity in details, and never duplicate state in the summary. Unknown or smaller usage skips compaction; a benign native refusal releases the attempt for later work. Skip prefixes containing foreign custom context. Never customize user manual or native threshold/overflow compaction, discard unfinished pre-patch work, create a State Flow origin, or rewrite Pi's append-only JSONL/tree.
-- Keep the injected runtime protocol compact and normative; put rationale and extended explanation in README rather than the model prompt. Foreign comment handling remains owned by other extensions.
+- Rotate the turn-stable specification on every user-initiated run. Persist the full specification only while that run is unfinished, then remove it atomically with accepted terminal response reconciliation. Enabled provider requests still receive current memory when Pi's actionable turn/settle boundaries continue without another `before_agent_start`; omit an absent specification rather than resurrecting the completed prompt, inventing a user run, or taking over Pi's continuation scheduler. Keep user-controlled specification text at user authority: never interpolate it into the system prompt; repeat it only in synthetic user runtime context. Treat materialized state in that message as fallible assistant-produced data whose transport role does not elevate it into user instructions.
+- When enabled inside an existing session, retain Pi's active context for exactly one complete bootstrap run and require its `patch_state` resolution to compile all future-relevant context.
+- Restore extension state from the active Pi branch's retained-boundary checkpoint and current canonical lineage, not the full entry list, a storage receipt, or Git `HEAD`, on startup and successful tree navigation.
+- Render compact status as accent `state-flow` plus dim `#<step>`. `/state-flow-status` must remain observational: show CWD/session keys, step, active temporal head, available hot-history depth, per-scope artifact/tail counts, and already-known invalidations; render only the effective global → CWD → session materialization as semantic JSON; perform no source reads, scans, fingerprinting, or maintenance. When temporal materialization is unavailable, report unknown counts and unavailable state rather than inventing empty projections.
+- Explicit `/state-flow-start` creates the canonical file store when missing and returns after local runtime acceptance without initializing or consulting Git. It initializes missing global, CWD, and current-session checkpoint/tail pairs plus session config/runtime metadata through compare-and-swap publication, enables only the current branch, and bootstraps prior conversation when needed. Explicit start on a proven pre-runtime branch establishes an empty session origin rather than importing a later same-session layer; shared streams remain live. Ordinary new sessions remain manual unless repository-global `autoStart` is true; configured new sessions may initialize missing CWD state and receive distinct empty session layers while inheriting global/CWD values. Resumed and tree-selected branches restore their retained canonical lineage regardless of that flag.
+- `/state-flow-stop` returns to the configured passive bootstrap/tool combination. For an accepted runtime, persist only the current session/branch's `config.enabled = false` and necessary runtime provenance, preserving all semantic checkpoints/tails and creating no semantic transition. A proven pre-runtime branch instead appends only the existing `{disabled:true}` Pi checkpoint; a cached passive view never authorizes runtime publication or a retained-boundary checkpoint. Only accepted canonical publication ends that pre-runtime condition. Preserve failed-selection fences, passive access, and later explicit Start/passive patch behavior. Lifecycle-only writes adopt unrelated live shared drift at a fresh origin when needed, without touching semantic/provenance files or counters; same-session races and explicit stale provenance writes still fail closed. Do not opportunistically fold tails or prune evidence during lifecycle persistence, even if another writer loaded a larger history limit. Refresh the host cache after adoption, freeze Stop's handoff from that accepted cache, and inspect newly adopted registered paths before the next enabled inference. Retain a frozen handoff plus the active user-run trajectory (including later tool results), post-stop conversation, and foreign context-bearing custom messages across same-physical-session reload/resume/tree. Exclude completed pre-run conversation only when the active boundary is proven. If a recorded active anchor is missing, nonfinite or ambiguous after native projection/compaction, reuse the active context selector and retain available summaries and tool trajectory; never fall back to the idle cutoff or reconstruct discarded raw entries. Idle Stop still retains only later conversation and foreign custom context. Active restart replaces passive mode but uses that bounded boundary for its one bootstrap run; new and forked physical sessions inherit neither projection. It does not rewrite agent-level `autoStart` or change its policy for future new sessions.
+- After an accepted non-bootstrap run settles with no pending input, State Flow may request native manual compaction under a generation-private marker only when public `getContextUsage()` reports at least 24,000 tokens. Keep the complete latest accepted run from its already captured first-user anchor, including steering and tool results; never substitute the last user message. Require one matching native user timestamp before the final assistant, otherwise skip rather than guessing. Store only retained boundary/step identity in details, and never duplicate state in the summary. Unknown or smaller usage skips compaction; a benign native refusal releases the attempt for later work. Await the native compaction completion/error callback inside the settled handler before returning, so Pi's deferred companion prompt dispatch cannot race an in-flight manual compaction; do not add a timer, queue or continuation owner. Skip prefixes containing foreign custom metadata or native `custom_message` context. Never customize user manual or native threshold/overflow compaction, discard unfinished pre-patch work, create a State Flow origin, or rewrite Pi's append-only JSONL/tree.
+- Keep the injected runtime protocol compact and normative; put rationale and extended explanation in README rather than the model prompt. Contribute initial active/passive protocol through Pi's native `systemPromptOptions.sections.state_flow`, not a returned forced `systemPrompt`; refresh only that owned section at `context_with_system` from current mode so in-flight Stop/Start and boundary continuations do not retain stale instructions. Keep section projection pure in the context domain, preserve unchanged arrays/native deltas and non-system identities, and never invent missing system frames. Preserve companion sections, tool declarations, native trace and explicit foreign forced-prompt precedence. Foreign comment handling remains owned by other extensions.
 - Do not claim strict boundedness for state, the current run trajectory, the turn specification, or the external full trace.
 - Remain extension-agnostic in core semantics, storage, and inference: core modules never import, name, special-case, or encode policy for another extension or transport. One optional leaf presentation adapter (`lib/telegram.ts`) may import public `pi-telegram` membranes to mirror the live status on exactly one main-menu section button and expose the same start/stop affordances already owned by `state-flow-start` and `state-flow-stop`; it must fail open when the transport is absent or its registry is unready and must never alter core behavior.
-- Activate State Flow model tools while an episode is enabled or passive tools are configured; preserve every unrelated active tool when toggling them. Passive reads never initialize storage, while an explicit passive patch may initialize or migrate storage without enabling episode barriers, continuation, or compaction. Keep mutation confined to `patch_state` and historical observation read-only.
+- Activate State Flow model tools while an episode is enabled or passive tools are configured; preserve every unrelated active tool when toggling them. Passive reads never initialize storage, while an explicit passive patch may initialize absent canonical storage without enabling an episode, continuation, or compaction. Unsupported predecessor storage is never converted. Keep mutation confined to `patch_state` and historical observation read-only.
 - Keep `.github/workflows/release.yml` as the sole version-tag release owner: it validates immutable tag identity, publishes through npm Trusted Publisher with provenance, verifies the public package, and only then creates the GitHub Release. Keep package, lockfile, tag, and changelog versions aligned; never add a long-lived npm token fallback.
 - Keep opt-in performance executables and workers in top-level `benchmarks/`; their correctness regressions stay in `tests/`. Benchmark workloads may reuse synthetic test fixtures, remain excluded from runtime packaging, and retain source-bound measurement identities across relocations.
 - Run `npm run validate` after retained code changes, then run the canonical ABCd context validator after context edits.

package/node_modules/@llblab/pi-state-flow/BACKLOG.md

@@ -1,5 +1,7 @@
-# BACKLOG
+# Backlog
 
-Completed implementation belongs in [CHANGELOG.md](CHANGELOG.md); durable semantic contracts belong in [AGENTS.md](AGENTS.md) and [docs/architecture.md](docs/architecture.md).
+No open implementation tasks.
 
-No open work.
+Completed outcomes are recorded in [CHANGELOG.md](CHANGELOG.md). Maintained contracts and acceptance evidence belong to [docs](docs/README.md).
+
+Live-host, provider and platform verification limits are documented in [SDK compatibility](docs/compatibility.md). Production-store conversion and installed-host activation remain separate operator decisions; see [usage and recovery](docs/usage.md).

package/node_modules/@llblab/pi-state-flow/CHANGELOG.md

@@ -2,7 +2,25 @@
 
 > Each release keeps at most 8 outcome records of at most 512 characters.
 
-## Unreleased
+## 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
 

package/node_modules/@llblab/pi-state-flow/README.md

@@ -4,93 +4,147 @@
 
 **Incremental scoped context/memory compiler for Pi.**
 
-Keep decisions, constraints, verified findings, and next steps without sending every completed tool exchange back to the model. State Flow compiles curated context and memory into explicit state; Pi still owns the conversation, the native tool loop, and the complete inspectable trace.
+State Flow maintains explicit state across requests and sessions. The agent incrementally compiles requirements, decisions, findings and source knowledge into durable memory rather than carrying every completed exchange into the next request.
 
-> Inspired by [SKILL.state](https://arxiv.org/html/2608.26263v2).
+Drawing on the explicit-state approach of [SKILL.state](https://arxiv.org/html/2608.26263v2), State Flow combines durable state with Pi's native conversation context. In this hybrid, **state carries continuity between user runs; Pi's native context carries the working trajectory within a run.** The conversation is not reset after each model response or tool call. Pi retains ownership of execution, session navigation and the full inspectable trace.
 
-## The idea
+## How it works
+
+A user run starts with effective memory and a new request. The agent works through Pi's ordinary inference/tool loop, updates memory when useful information changes, and returns an ordinary answer. The next run receives the accepted state and compact recent transitions instead of the completed ordinary conversation history.
 
 ```text
-Current state + New request
-              ↓
-   Pi's native tool loop
-              ↓
-Updated state + Answer
-              ↓
-          Next request
+Current state + Request
+          ↓
+Pi's native tool loop
+          ↓
+Patched state + Answer
+          ↓
+Updated state
 ```
 
-During a request, the model retains the current tool trajectory. Between requests, State Flow replaces completed ordinary conversation history in model context with the current state and recent transitions. It does not delete Pi's session history.
+Within a run, the available request, intermediate responses, tool results and steering remain in context. A state patch updates memory without discarding that working trajectory. Persistent context-bearing messages from other extensions are preserved as well.
+
+This reduces reliance on repeated model-generated summaries of an accumulating transcript. Retaining the current trajectory also allows prompt-cache reuse while the relevant prefix remains unchanged. Avoiding summary calls and repeated prompt processing can improve responsiveness; the result depends on the model, provider, workload and frequency of state changes, not a fixed latency guarantee.
 
-The agent curates what matters; the extension validates, persists, and projects the accepted state. This is working memory, not automatic proof that a remembered fact is true.
+Native compaction remains available for long runs. State Flow may also request a completed-history boundary without another model summary, retaining the complete latest accepted run. Neither mechanism deletes Pi's append-only session trace. See [lifecycle behavior](docs/usage.md#session-behavior) and [performance evidence](docs/performance.md).
 
-## Quick start
+## Installation and activation
 
-Requires Pi `0.84.4` or newer and Node.js `22.19.0` or newer. There is no declared upper Pi version bound; see the [SDK compatibility matrix](docs/compatibility.md) for exact tested stacks. Git is optional; using it requires a configured commit identity.
+Requires **Pi 0.87.0+** and **Node.js 22.19.0+**. See [SDK compatibility](docs/compatibility.md) for tested stacks and verification limits.
 
-From npm:
+From NPM:
 
 ```bash
 pi install npm:@llblab/pi-state-flow
 ```
 
-From git:
+From Git:
 
 ```bash
 pi install git:github.com/llblab/pi-state-flow
 ```
 
-In Pi:
+Enable active State Flow on the current branch:
 
 ```text
 /state-flow-start
 ```
 
-Continue working normally. The agent receives the state protocol and uses `patch_state` to maintain memory.
+Starting in an existing conversation retains its context for one complete bootstrap run so the agent can compile what matters.
+
+- `/state-flow-start`: Enable active state updates and memory-based context projection.
+- `/state-flow-status`: Inspect effective state, retained history and known recovery issues without scanning sources or changing state.
+- `/state-flow-stop`: End active episode semantics without deleting memory; an interrupted run retains its frozen handoff and available trajectory.
+
+Active mode is **opt-in**. Passive memory projection and the memory tools are enabled by default: existing state can be read or explicitly patched without an active episode or State Flow compaction. Stop returns to the configured passive behavior. `autoStart` can enable active mode for genuinely new sessions; resumed branches restore their own enablement. See [configuration](docs/usage.md#configuration).
+
+## State model
+
+### Scopes and effective memory
 
-- `/state-flow-status`: Inspect the selected state, history, artifact freshness, and publication status.
-- `/state-flow-stop`: Disable updates on this branch without deleting retained state.
+Memory has three ownership scopes:
 
-Active State Flow episodes remain **opt-in**, while passive durable memory bootstrap and tools are available by default. Passive turns never require `final:true`, continue automatically, or trigger State Flow compaction. Starting an active episode in an existing conversation keeps its context for one migration run; set `"autoStart": true` to promote genuinely new sessions automatically. See [configuration](docs/usage.md#configuration).
+- `global`: Knowledge and preferences shared across projects.
+- `cwd`: Knowledge shared by sessions in the same working directory.
+- `session`: State belonging to the current session and its selected branch.
 
-## What carries forward
+They compose recursively in **global → CWD → session** order. More-specific values override lower-scope values, while object fields merge. Removing a local value can reveal an inherited value again.
 
-The same semantic planes exist at every scope:
+The agent receives the **effective view** of this composition, not three unrelated memory dumps. It can read that view or inspect an individual scope when ownership matters. `effective` is a computed view, not a fourth storage scope. Scope precedence does not elevate memory into system-level instructions.
 
-- `contract`: Requirements, decisions, constraints, and interface commitments.
-- `working`: Observations, results, unresolved questions, and possible next steps.
-- `intents`: Courses of action the agent has actually committed to pursue.
-- `artifacts`: Source-addressed descriptions and reusable compiled knowledge.
+### Semantic planes
+
+Every scope uses the same shape:
+
+- `intents`: Active commitments to future action.
+- `contract`: Requirements, decisions, constraints and interface commitments.
+- `working`: Observations, results, uncertainties and current continuation.
+- `artifacts`: Source-addressed descriptions and compiled knowledge.
 - `response`: The latest complete answer, captured by the runtime.
-- `lazy`: Durable, versioned memory omitted from ordinary context until explicitly read.
+- `lazy`: Supporting memory available through explicit reads, with its body omitted from baseline model context.
+
+These planes organize ordinary JSON rather than imposing a project-specific schema. The model updates the semantic planes except `response`, which is runtime-owned. Memory remains fallible: storing an observation does not make it current or correct.
+
+## Incremental updates and history
+
+`patch_state` updates one or more named scopes atomically. Unmentioned values remain unchanged; object patches merge recursively, and `null` deletes an object key rather than becoming stored data.
+
+```json
+{
+  "cwd": {
+    "contract": { "verification": { "command": "npm test" } }
+  },
+  "session": {
+    "intents": { "verify": { "action": "Run the checks before publishing" } },
+    "working": { "checks": "Pending" }
+  }
+}
+```
+
+During an active episode, a material patch is an inference barrier: sibling tool calls are blocked, and the next inference sees the accepted effective state. Ordinary completion needs no finalization patch or additional State Flow reasoning loop.
+
+`read_state` provides targeted current and historical access:
+
+```json
+{ "paths": ["effective.contract", "cwd.working", "session.intents"] }
+```
+
+- `working`: Current effective working memory; unscoped paths are effective aliases.
+- `effective[1].working`: Working memory at the preceding accepted transition boundary, when retained.
+- `cwd.patches[0]`: The latest retained CWD semantic patch.
+- `effective.lazy.memory[0..3]`: A bounded slice of a stored collection.
+
+Historical materializations and scope patch histories use the configurable **`historyLimit`**, from **0 to 100**, with a default of **7**. Materialized offsets refer to accepted semantic transitions, not user messages or an independent counter for each scope. Requested history must still exist in the active lineage; increasing the limit cannot recreate discarded history. Older patches fold into the checkpoint without removing current values.
+
+Array ranges, structural `keys` reads and path-intersected `patch` projections support progressive access without loading whole memory collections. See [progressive memory](docs/lazy-state.md) and [tool contracts](docs/architecture.md#model-tools).
+
+## Persistence, backups and continuity
+
+The default store is `~/.pi/agent/state-flow/`, independent of registered source files. Canonical `checkpoint.json`, `patches.jsonl` and `meta.json` files hold each scope's state, retained changes and metadata; session configuration and runtime identity are stored separately.
 
-Memory overlays **global → project CWD → session**. Put reusable cross-project knowledge in global, project knowledge in CWD, and private task continuation in session. Hot planes carry what must matter now; `lazy` retains what may matter later without hydrating its body into every prompt. An intent stays hot only while its course remains chosen and disappears when fulfilled, abandoned, superseded, or impossible. It may refer to supporting detail through a structured `{"$ref":"cwd.lazy.plan"}` value or a `$`-prefixed state path inside ordinary prose, such as `$effective.lazy.memory[7]`. Both remain semantic content interpreted by the agent: State Flow never parses, validates, hydrates, executes, or completes them automatically. The agent never scans references for breakage. Only when current work already follows one and a single value path is missing does State Flow perform a bounded exact reverse lookup. Matching durable sources produce a top-level `{value:null, hint:[...]}` sentinel whose typed hint names runtime-verified current owning paths and asks the agent to reconcile them. Keys, patch, batch, and unmatched reads retain ordinary all-or-error behavior; no match does not prove that the agent invented the path. The agent may then repair or remove a proven stale locator in its owning value.
+**Git backups are optional.** When the store is a configured Git repository, accepted active turns may create versioned backups of State Flow-owned files. Backup needs a Git commit identity; accepting and persisting state does not. A backup failure produces a warning without rejecting or rolling back accepted memory. Git history can be inspected separately, but it is not the authority for `read_state` or automatic restoration of expired semantic boundaries.
 
-**Resuming an existing Pi session restores its selected State Flow state and enablement.** A genuinely new session starts with an empty session layer and inherits only shared global/CWD memory; it does not resume another session's private work. Tree navigation follows the selected branch, not whichever state happens to be at Git `HEAD`.
+Resume and tree navigation restore the selected retained session boundary over current shared global/CWD memory. A new session gets its own session layer. Supported native forks copy selected session state into a new owner without changing the parent's private data. Expired, incomplete or contradictory boundaries fail closed rather than silently substituting newer state. See [fork support](docs/usage.md#fork-support-and-limits) and [storage recovery](docs/usage.md#storage-and-recovery).
 
-The agent uses `read_state` for exact current or historical paths. Unscoped paths read the effective overlay; `global`, `cwd`, and `session` address ownership directly; `[n]` selects one of up to seven prior accepted transition boundaries. Bounded array ranges and `value`, `keys`, or `patch` projections support progressive reads without hydrating whole lazy collections. Git-backed stores retain older committed history separately.
+Version 0.17 accepts only the current canonical storage contract and has no in-place predecessor converter. Preserve existing data and check the [format boundary](docs/usage.md#moving-a-store-and-the-017-format-boundary) before changing versions or moving a store.
 
-Two packaged Skills keep guidance proportional: `state-flow-guide` resolves concrete operational questions about reading, patching, inheritance, acquisition, finalization, and recovery; `state-flow-memory` performs one bounded explicit or phase-boundary curation. Neither runs background maintenance.
+## Operational boundaries
 
-## Boundaries worth knowing
+State Flow adds memory, not another agent controller. It does not introduce background reasoning, a scheduler, automatic reference hydration or rollback of external tool effects. State and the current trajectory are not size-capped; performance depends on how much useful information the agent retains.
 
-- `Not a second agent loop`: State Flow adds memory to Pi; it does not run background reasoning or replace session controls.
-- `Not a transcript archive in the prompt`: Prefer ordinary Pi when each request needs all historical exchanges verbatim.
-- `Not live workspace truth`: Remembered observations can become stale; revalidate consequential facts before acting.
-- `Physical forks copy private memory`: Native fork replacement copies the selected session checkpoint/tail into a new owner while retaining current shared memory. The child starts its own history; older parent checkpoints are not child history. See [fork support and limits](docs/usage.md#fork-support-and-limits).
-- `Not a token or latency guarantee`: State and the current trajectory are not size-capped. Benefits depend on workload and memory quality; see [performance evidence](docs/performance.md).
-- `Use a dedicated store`: By default state lives in `~/.pi/agent/state-flow/`, separately from Knowledge Markdown. Git commits include the store's complete non-ignored worktree delta. Do not point it at an unrelated working repository.
-- `Treat memory as private`: State and diagnostic logs may contain session content. Keep secrets out, and review data before configuring a remote. Removing a value does not erase Git history or other copies.
+The packaged `state-flow-guide` Skill covers concrete operations and recovery. `state-flow-memory` supports explicitly requested curation, for example: **“Review and clean State Flow state”** Normal handoffs reconcile touched memory; dedicated cleanup is not an automatic audit after each task.
 
-Pi packages run with your user permissions. Without Git, current state and its proven hot history persist to files, but arbitrary older branches may be unavailable. See [storage and recovery](docs/usage.md#storage-and-recovery) before moving stores.
+Treat state, diagnostic logs and backups as private data. Revalidate consequential observations before acting, and verify a transfer's destination before deleting its source. Removing a value from current state does not erase older histories or remote copies.
 
-## Read more
+## Documentation and development
 
-- [Usage and recovery](docs/usage.md): Configuration, session behavior, diagnostics, privacy, and storage recovery.
-- [Architecture](docs/architecture.md): Semantic state, temporal history, barriers, artifacts, and integration contracts.
-- [Performance](docs/performance.md): Reproducible workloads, measured costs, and what the measurements do not prove.
-- [Documentation index](docs/README.md): All maintained guides, including the temporal acceptance map.
+- [Usage and recovery](docs/usage.md) — Configuration, lifecycle, diagnostics and storage operations.
+- [Architecture](docs/architecture.md) — Semantic model, temporal boundaries, artifacts and integration contracts.
+- [SDK compatibility](docs/compatibility.md) — Tested stacks and verification limits.
+- [Performance](docs/performance.md) — Measurements, workload definitions and limits.
+- [Acceptance map](docs/temporal-acceptance.md) — Properties tied to concrete tests.
+- [Documentation index](docs/README.md) — All maintained guides.
 
-For development, run `npm install` and `npm run validate`. `npm run benchmark` runs the opt-in synthetic workload in `benchmarks/`, separate from the normal test suite. In a source checkout, see `benchmarks/README.md` for lifecycle/publisher selection.
+For development, run `npm install` and `npm run validate`. `npm run benchmark` is opt-in and separate from the normal suite; see `benchmarks/README.md` in a source checkout.
 
-Project context: [AGENTS.md](AGENTS.md) · [BACKLOG.md](BACKLOG.md) · [CHANGELOG.md](CHANGELOG.md).
+Project context: [AGENTS.md](AGENTS.md), [BACKLOG.md](BACKLOG.md), [CHANGELOG.md](CHANGELOG.md).