@llblab/pi-kit 0.5.2 → 0.7.0

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

@@ -1,3 +1,126 @@
-# Backlog
+# BACKLOG
 
-No planned work.
+Canonical proposed work for **pi-state-flow 0.6.0 — Continuity without fixation**.
+
+Baseline: **0.5.0**, commit `feed43c33db7f4a7f9c10a7eda619a2ffc2c91b5`, inspected on 2026-09-09. This document specifies work; it does not report implementation or validation results. Reconcile with newer repository work before editing.
+
+## Release contract
+
+A fresh State Flow run should inherit the consequences of previous work: active commitments, established observations, bounded negative results, meaningful corrections, unresolved decision-relevant uncertainty, and the exact point of continuation. It should not inherit an unapproved method as a requirement or an earlier inference as established truth.
+
+Implement this through the existing runtime protocol, the explicit curation Skill, and focused regression coverage. Do not build a new memory engine. More novelty, smaller state, and zero repeated work are not independent success criteria.
+
+**Done:** the runtime and Skill express consistent memory rules; the documented curation sequence is executable with current tools and compilation obligations; compatibility regressions pass. Semantic quality remains a model-judgment boundary rather than a deterministic transport claim.
+
+## Fixed boundaries
+
+- Keep the semantic shape exactly `artifacts`, `contract`, `working`, `response`, with existing flexible object contents and `global → cwd → session` overlay.
+- Preserve `checkpoint.json` / `patches.jsonl`, shared causal boundaries, hot offsets 0–7, Git/file-only guarantees, branch restoration, and local acceptance versus remote publication.
+- Preserve the native tool loop, complete current-run trajectory, inspectable Pi trace, bootstrap behavior, and removal of completed trajectories only at user-run boundaries. No extra resets or forced exploratory reruns.
+- Keep `patch_state` single-scope and the sole semantic mutation tool. Keep terminal multi-scope reconciliation, runtime-owned response, and strict inference barriers.
+- No required per-item confidence/provenance/status schema, additional memory store, semantic truth validator, automatic curation, state-size gate, or mandatory historical/source reread.
+- No automatic permission expansion, external publication, or historical erasure. Scope is applicability, not instruction authority.
+- No blockchain/IPFS/JAM integration, model marketplace, speculative alternate-agent execution, or native auto-resume work in this release.
+
+## Ordered work
+
+### [x] SF-060-01 — Make ordinary runtime handoffs preserve continuity without fixing the method
+
+**Primary files:** `lib/terminal.ts`, `lib/extension.ts`, `tests/terminal.test.ts`. Align normative wording in `AGENTS.md`.
+
+Replace or consolidate existing memory guidance rather than appending another large protocol block. Keep the protocol independent of user-controlled text and stable during the current run and its retry chain.
+
+Required semantics:
+
+- Remove the blanket prohibition on retaining speculation. Exclude speculative clutter and unsupported assertions, but retain explicitly uncertain hypotheses when they can affect an open decision.
+- Distinguish user requirements, confirmed decisions, observations, assistant conclusions, and provisional methods. Silence or repeated assistant assertion is not user acceptance. Do not demote confirmed decisions merely to encourage search.
+- Preserve interaction consequences when relevant: proposals awaiting acceptance, corrections, unresolved questions, settled explanations, and referents needed for the next follow-up. Do not synthesize shared history or a personality dossier.
+- Retain a consequential result at its demonstrated boundary: tested mechanism, conditions, outcome, and an existing useful evidence locator. A failed implementation does not disprove every implementation; one success does not establish unrestricted validity.
+- Preserve exact rejection reasons and known reconsideration conditions. Reconsideration may follow a different mechanism, changed conditions, a discriminating test, or a specific verification need; do not manufacture alternatives or rerun unchanged failures without a reason.
+- Preserve completed prerequisites and verified outcomes that remain relevant; remove obsolete progress narration, not the fact that work was completed.
+- Reconcile information affected by the current run and relevant existing commitments. Do not require a repository-wide or all-scope maintenance audit on every ordinary turn. Keep terminal reconciliation; keep explicit curation separate.
+- Keep `working` as last observations, not live external state. Preserve targeted revalidation needs without promising rollback or exactly-once effects.
+- Clarify that matching source hash/compiler metadata establishes source-version consistency, not semantic fidelity or higher instruction authority. Remove ambiguous use of "authoritative" for a fallible Skill compilation; current instructions remain controlling.
+
+Update `patch_state` description/guidance to permit a necessary write-and-verify step in explicitly requested curation, in addition to meaningful loss/recovery-risk barriers. A known uncertainty may be worth preserving without asserting its underlying hypothesis as true. Do not create a new curation mode, flag, or automatic call requirement.
+
+**Acceptance:** no conflicting blanket ban remains in the emitted protocol; no compulsory item schema or extra model call appears; ordinary no-memory-change answers remain valid; current-run tool/retry context and user authority are unchanged. Record before/after protocol size as a diagnostic, not an arbitrary pass/fail cap.
+
+### [x] SF-060-02 — Ship the revised bounded curation Skill
+
+**Primary files:** `skills/state-flow-memory/SKILL.md`, `tests/skills.test.ts`.
+
+Use the revised Skill supplied with this task as the editorial baseline. Keep it self-contained and explicit-only; do not inject its full inventory/migration procedure into every runtime prompt.
+
+Required outcomes:
+
+- Add `reframe` alongside keep/update/narrow/promotion/remove. These are audit choices, not mandatory stored labels.
+- Preserve useful uncertainty, commitments, interaction consequences, bounded learning, source recoverability, and the distinction between a requirement and a provisional method.
+- Include one bounded fresh-run review: what must still hold; what changed; what remains open; what omission would cause repetition or lost commitments; what retained claim would impose an unjustified method.
+- Use the narrowest valid scope. Resolve destination conflicts before movement; write and verify the destination before deleting the source; inspect the effective overlay afterward. Separate tool calls are not atomic migration.
+- Preserve an accepted source copy on unverified external promotion. Verify destination identity, content and revision through the actual interface; a stored assertion of acceptance is not a receipt. Preserve routing necessary for later retrieval.
+- Report partial migration, unavailable evidence, and historical secret-retention limits truthfully. Do not expose secrets in the report or equate active-state deletion with historical erasure.
+- Stop after the requested cohort, including an unchanged or blocked result. Do not start a project investigation or an automatic audit merely to improve memory.
+
+**Acceptance:** Pi discovers the Skill without diagnostics; its activation remains explicit; the revised policy does not contradict SF-060-01; tests assert the relevant contract rather than preserving obsolete wording. A justified reread of the changed Skill refreshes its existing path-keyed artifact through normal compilation. Do not invalidate unrelated artifacts or invent a new compiler revision solely for this prose change.
+
+### [x] SF-060-03 — Prove the Skill can complete curation through existing barriers
+
+**Primary files:** `lib/extension.ts`, `lib/transition.ts` (verification targets); `tests/skills.test.ts`, `tests/transition.test.ts`, `tests/integration.test.ts`; relevant protocol/Skill instructions.
+
+The baseline already clears successful acquisition trackers after an accepted `commitStage`. Do not add a new tracker lifecycle on the assumption that accepted reads remain pending. The actual scheduling constraint is that pending Skill reads require CWD compilation and pending invalidated ordinary Markdown reads require global compilation at the next accepting transition.
+
+Document and regression-test this executable sequence:
+
+1. Read the curation Skill when needed; accept its required CWD compilation before accumulating a global compilation obligation.
+2. Read the smallest required state projections. Read a stale ordinary Markdown source only for a justified gap; accept its global compilation before proceeding with unrelated single-scope writes.
+3. Write the migration destination using `patch_state`, verify it with a separate `read_state`, then delete/narrow the source and verify the resulting scope/effective state.
+4. Complete one terminal reconciliation without repeating already accepted compilations or inventing memory changes.
+
+Do not depend on read-after-write inspection following a terminal answer; readback must occur after tool barriers, before final reporting. Do not weaken compiler validation or introduce multi-scope `patch_state` to solve a scheduling problem.
+
+Cover these boundaries:
+
+- A Skill read followed by an unrelated session/global patch without required compilation is rejected without accepting state; the documented compilation-first route succeeds.
+- Simultaneously pending CWD/global acquisition remains subject to the existing complete-compilation rule. Test rejection of insufficient single-scope patches and acceptance through existing multi-scope terminal reconciliation. Do not silently discard obligations or claim an unperformed curation was verified.
+- Accepted compilation clears only completed acquisition work; a failed acceptance does not authorize dropping it. Existing trusted hash/compiler and source-refresh checks remain effective.
+- Destination failure preserves the source; source-deletion failure leaves a recoverable duplicate and is reported as incomplete. Inherited values exposed by deletion are visible to verification.
+- No-op memory curation introduces no fabricated memory changes. A changed final response may still create a semantic transition under the existing contract.
+- Reader siblings remain blocked by `patch_state`; read-only verification creates no transition. A successful local acceptance is not repeated because remote replication failed.
+
+**Acceptance:** tests exercise actual tool/event ordering, not only hand-authored terminal patches. Use the real Pi SDK fixture where lifecycle behavior matters, clearly labeling its scripted provider. Existing validators and public tool schemas remain intact. Change production logic only for an observed regression within this sequence, with a reproducer; no speculative refactor.
+
+### [x] SF-060-05 — Align documentation, preserve compatibility, and prepare release
+
+**Primary files:** `AGENTS.md`, `README.md`, `docs/architecture.md`, `CHANGELOG.md`, `package.json`, `package-lock.json`, and this backlog.
+
+- Describe ordinary handoff versus explicit curation consistently, including useful uncertainty, confirmed decisions, bounded negative results and interaction consequences.
+- Remove conditional language suggesting global memory is a feature switch. Clarify that a valid state/receipt does not prove semantic truth, useful curation, or historical deletion.
+- Document compilation-first curation scheduling and the existing mixed-acquisition limitation. Do not advertise a new atomic multi-scope tool operation.
+- Keep existing 0.5.0 Git-backed and file-only states readable without schema migration, bulk rewrite or invented semantic transitions. Protocol changes do not retroactively certify old memory or rewrite historical revisions. Refresh changed Skill content through justified acquisition, not a global startup rebuild.
+- Keep current-run/native trace behavior, temporal offsets, scope isolation, response finalization and publication behavior covered by the existing test suite. Add only focused compatibility cases that are missing.
+- Prepare version 0.6.0 in package and lockfile, concise release notes, and a requirement-to-test/evidence map for SF-060-01 through SF-060-03. Record what was actually run and any remaining limitations.
+
+**Acceptance:** `npm run validate` passes; packed content includes the revised Skill and documentation; no new storage/config/tool contract or production dependency is introduced. Packaging and release follow existing repository gates. Preparing the release does not authorize commits, tags, pushes, npm publication or GitHub release creation.
+
+## Dependencies and stopping rule
+
+`SF-060-01 → SF-060-02 → SF-060-03`; `SF-060-05` closes the release.
+
+Each item closes with its diff, targeted proof and unresolved limitations. Split a large proof into smaller cases under the same item; do not enlarge product scope. Newly discovered adjacent issues go into a deferred section unless they prevent this release contract from holding.
+
+Stop when the four items and release checks are satisfied. Do not prolong 0.6.0 to seek universal semantic guarantees or a redesigned memory system.
+
+## Deferred host integration — preserved from 0.5.0
+
+- [ ] **Native default session continuation:** Integrate existing read-only recommendation, exact selection and knowledge-bootstrap contracts before Pi creates `SessionManager`, preserving explicit new/resume precedence, truthful notices and cross-process session ownership. The recorded 0.5.0 blocker is the lack of a suitable Pi pre-session resolver hook; reverify upstream support when taking this item. It is not a 0.6.0 release dependency.
+
+## Baseline evidence
+
+The findings above come from inspection of this pinned revision, not an execution of its tests:
+
+- [Runtime protocol and terminal handling](https://github.com/llblab/pi-state-flow/blob/feed43c33db7f4a7f9c10a7eda619a2ffc2c91b5/lib/terminal.ts): blanket speculation prohibition coexists with preserving decision-relevant hypotheses; terminal reconciliation already exists.
+- [Extension wiring](https://github.com/llblab/pi-state-flow/blob/feed43c33db7f4a7f9c10a7eda619a2ffc2c91b5/lib/extension.ts): compilation trackers clear after accepted commit; context projection and barrier lifecycle are already implemented.
+- [Transition validation](https://github.com/llblab/pi-state-flow/blob/feed43c33db7f4a7f9c10a7eda619a2ffc2c91b5/lib/transition.ts): required compiler outputs are scoped, and the single-scope tool and multi-scope terminal share staging.
+- [Existing curation tests](https://github.com/llblab/pi-state-flow/blob/feed43c33db7f4a7f9c10a7eda619a2ffc2c91b5/tests/skills.test.ts): the existing narrowing example uses a terminal multi-scope patch rather than the complete read/compile/write/readback sequence.
+- [Contributor invariants](https://github.com/llblab/pi-state-flow/blob/feed43c33db7f4a7f9c10a7eda619a2ffc2c91b5/AGENTS.md) and [existing backlog](https://github.com/llblab/pi-state-flow/blob/feed43c33db7f4a7f9c10a7eda619a2ffc2c91b5/BACKLOG.md): unchanged engine boundaries and deferred host work.

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

@@ -1,79 +1,121 @@
 # Changelog
 
+> Each release keeps at most 8 outcome records of at most 512 characters.
+
+## 0.6.0: Continuity without fixation
+
+- `Memory`: Revised ordinary handoffs to preserve confirmed decisions, useful uncertainty, interaction consequences, completed prerequisites, bounded positive and negative results, and exact continuation without promoting provisional methods or unsupported assertions.
+- `Skill`: Expanded the explicit `state-flow-memory` Skill with reframing, one bounded fresh-run review, compilation-first scheduling, write/readback/delete scope migration, recoverable partial results, and evidence-gated external promotion.
+- `Curation`: Added regression coverage for the executable curation barrier sequence while preserving single-scope `patch_state`, terminal multi-scope reconciliation, trusted compiler metadata, native tool context, and local acceptance independently from remote replication.
+- `Compatibility`: Preserved the 0.5.0 semantic shape and Git/file storage without migration, bulk rewrite, new dependency, or new runtime/config/tool contract.
+
+## 0.5.0: Durable memory, compiled routing, and local-first publication
+
+- `Publication`: Decoupled immediate local Git acceptance from optional remote replication with persisted `off`/`turn-end`/legacy `transition` policy, a symlink-safe CAS queue, descendant-only coalescing, asynchronous non-interactive workers, restart recovery, concurrency-safe confirmation, and truthful status diagnostics.
+- `Memory`: Made State Flow the unconditional durable-memory owner while enabled, with global semantic memory always available at the narrowest correct scope; external promotion pointers remain optional semantic handoff records rather than runtime ownership configuration.
+- `Artifacts`: Added extensible compiled artifact metadata, validated tags, deterministic candidate routing, and bounded visible source rehydration without persisting source bodies or treating routing as read authorization.
+- `Continuation`: Added read-only native-session discovery, exact State Flow provenance checks, deterministic continuation ranking, and bootstrap planning while keeping automatic default resume deferred until Pi exposes a pre-session resolver hook.
+- `Identity`: Unified Pi's session UUID and native storage key as one runtime address, centralized extension runtime construction, and skipped obsolete hashed-path probing once canonical CWD materialization is proven.
+- `Validation`: Replaced transient semantic-equality SHA-256 calculations with validated structural JSON comparison while retaining cryptographic hashes for durable identity, freshness, integrity, CAS, and fingerprints.
+- `Transcript`: Restored the empty-line boundary between the `patch_state` tool call and its materialization result in Pi and Telegram transcript rendering.
+- `Skill`: Bundled the optional `state-flow-memory` Skill for explicit bounded audits, scope narrowing, contradiction cleanup, and evidence-gated external handoff without background maintenance.
+
+## 0.4.0: Temporal state and independent durable storage
+
+### Temporal state
+
+- `Temporal`: Rebuilt materialized state on one parent-linked causal lineage. `state[0..7]` and each global/CWD/session projection now resolve the same accepted boundary, sparse multi-scope changes share one identity, response-only changes advance history, and semantic no-ops do not.
+- `Temporal`: Added enabled-only `read_state` for lazy effective or scoped reads at offsets zero through seven. Reads use the cached checkpoint/tail runtime without publishing, while `patch_state` remains the sole mutator and an immediate inference barrier.
+- `Lifecycle`: Preserved Pi's native tool loop and full inspectable session trace while reconciling each finalized answer into session response exactly once. New sessions inherit shared scopes without rewriting them; resume, tree navigation, stop, and pre-runtime branch starts preserve branch-local provenance.
+
+### Storage and recovery
+
+- `Storage`: Moved runtime state out of Knowledge into the independently configurable `agentDir/state-flow` store. Canonical scope files are anchored `checkpoint.json` plus bounded replayable `patches.jsonl`, with separate session `config.json` and `meta.json`; strict revision-only Pi checkpoints replace copied semantic snapshots.
+- `Storage`: Made Git optional. File-only mode preserves the exact current cohort and hot history when the executable is absent; Git mode commits every accepted cohort immediately, keeps local-only repositories valid, retries the exact commit after remote failure, and adopts populated file stores without inventing earlier history.
+- `Identity`: Aligned CWD and session directories with Pi's native readable layout, including JSONL filename stems and header-derived in-memory session names. Canonical owner metadata retains collision/foreign-identity checks; current Git-backed SHA-suffixed development stores migrate transactionally, while old Git revisions remain readable.
+- `Recovery`: Added conservative current-state migration and branch restoration without checkout/reset. Historical reads select Git objects directly; unavailable pointers never authorize substituting live files, and changing the configured store does not silently relocate Knowledge-backed history.
+- `Publication`: Hardened publication with shared exclusion, isolated indexes, exact prepared-byte receipts, compare-and-swap checks, symlink/path rejection, unrelated staging preservation, and conflict-aware byte-exact rollback.
+
+### Configuration, context, and diagnostics
+
+- `Configuration`: Added strict agent-level `state-flow.json`: `directory` selects storage and `autoStart` defaults to `false` for genuinely new sessions only. Absolute, config-relative, and home-relative paths are supported; SDK storage and Knowledge roots remain independent overrides.
+- `Context`: Retained the canonical `artifacts`, `contract`, `working`, and `response` semantic shape, with recursive global → CWD → session overlay. Knowledge Markdown and Skill acquisition now use source-addressed, runtime-hashed artifact compilations and materialized-first read policy rather than raw-body injection.
+- `Diagnostics`: Expanded status and acceptance documentation for selected revisions, active temporal boundaries, hot-history depth, retained scope tails, artifact freshness, pending publication, unavailable materialization, and all twenty temporal properties.
+
 ## 0.3.0: Optional memory patches and evidence-aware handoffs
 
-- Require targeted revalidation of volatile observations and inspection of external effects after interruption or branch navigation; missing memory proves neither success nor absence of effects. Document the absence of rollback/freshness guarantees and preserve the restriction on routine Skill rereads. Add instruction-presence tests, not semantic or integration guarantees.
-- Strengthen the handoff protocol with evidence-aware continuation, requirement/observation/hypothesis distinctions, conditional rejections, and contradiction reconciliation; preserve decision-relevant uncertainty during optimization. Add instruction-presence regressions, not semantic guarantees. Increase the protocol-only character budget to 3,700 (3,900 with bootstrap) for these obligations; state remains uncapped.
-- Accept ordinary non-empty terminal answers as empty memory patches: preserve memory and update the response without unnecessary regeneration, including answers split across text blocks.
-- Keep malformed explicit envelopes and missing Skill compilations on the existing bounded validation path.
-- Clear the backlog; documented integration and continuation-quality limitations remain, not release commitments.
+- `Reality`: Require targeted revalidation of volatile observations and inspection of external effects after interruption or branch navigation; missing memory proves neither success nor absence of effects. Document the absence of rollback/freshness guarantees and preserve the restriction on routine Skill rereads. Add instruction-presence tests, not semantic or integration guarantees.
+- `Memory`: Strengthen the handoff protocol with evidence-aware continuation, requirement/observation/hypothesis distinctions, conditional rejections, and contradiction reconciliation; preserve decision-relevant uncertainty during optimization. Add instruction-presence regressions, not semantic guarantees. Increase the protocol-only character budget to 3,700 (3,900 with bootstrap) for these obligations; state remains uncapped.
+- `Terminal`: Accept ordinary non-empty terminal answers as empty memory patches: preserve memory and update the response without unnecessary regeneration, including answers split across text blocks.
+- `Validation`: Keep malformed explicit envelopes and missing Skill compilations on the existing bounded validation path.
+- `Planning`: Clear the backlog; documented integration and continuation-quality limitations remain, not release commitments.
 
 ## 0.2.3: Document protocol and validation limitations
 
-- Document that duplicate-comment detection also rejects literal State Flow envelope examples inside fenced or inline code in terminal answers, and provide a plain-JSON workaround.
-- Clarify that mock lifecycle tests are not real Pi scheduler integration checks and that structural validation cannot guarantee semantic memory retention.
-- No runtime behavior changes.
+- `Terminal`: Document that duplicate-comment detection also rejects literal State Flow envelope examples inside fenced or inline code in terminal answers, and provide a plain-JSON workaround.
+- `Validation`: Clarify that mock lifecycle tests are not real Pi scheduler integration checks and that structural validation cannot guarantee semantic memory retention.
+- `Runtime`: No runtime behavior changes.
 
 ## 0.2.2: README structure hotfix
 
-- Separate installation from usage, remove the redundant quick-start section, and move architecture details after the user-facing documentation.
+- `Documentation`: Separate installation from usage, remove the redundant quick-start section, and move architecture details after the user-facing documentation.
 
 ## 0.2.1: README banner hotfix
 
-- Add the project banner to the README.
+- `Documentation`: Add the project banner to the README.
 
 ## 0.2.0: Modular runtime hardening
 
-- Add a task-first README quick start with explicit compatibility, opt-in behavior, one-off trial instructions, and Pi package security guidance.
-- Tighten the normative runtime protocol and enforce a regression-tested character budget; omit absent validation feedback from synthetic runtime context instead of serializing a redundant `null`.
-- Redistribute lifecycle coverage from the former monolithic extension suite into the corresponding mirrored domain suites, leaving `extension.test.ts` focused on composition and using one shared test harness.
-- Split the runtime into independent `json`, `state`, `episode`, `snapshot`, `session`, `recovery`, `status`, `context`, `skills`, `terminal`, `validation`, `transition`, and `extension` modules under `lib/`; isolate explicit episode transitions, active-branch selection and recovery, status rendering, bounded retry decisions, atomic state staging, and compare-and-swap commits; mirror each domain under `tests/`, enforce an acyclic dependency graph with cross-domain invariant tests, and reduce `index.ts` to composition and public exports.
-- Register lifecycle commands in the canonical start, status, stop order.
-- Centralize synthetic runtime-context construction and private validation-message filtering in the independently tested context domain, keeping user-controlled specifications out of system-prompt composition.
-- Keep State Flow enabled and preserve the last committed state when terminal-validation retries are exhausted; only the transient retry chain is abandoned so the next user request can continue reliably.
-- Track Skill reads through an independently tested lifecycle correlator in Pi's actual `tool_execution_start` → `tool_call` event order while retaining the mutable intercepted input reference, so later argument rewrites are attributed to the executed path.
-- Discard mismatched lifecycle records defensively so a stale or reused tool-call id cannot produce false Skill acquisition.
-- Bound restored iteration and validation-attempt counters before incrementing them, reject exhausted live iteration counters explicitly, and cover both safe-integer boundaries so malformed branch metadata cannot corrupt retry accounting or status output.
-- Reject restored non-JSON state values such as non-finite numbers before they can break hashing or silently materialize as `null`.
-- Fall back past malformed newer checkpoints to the newest valid active-branch snapshot, while still failing closed on cyclic or hostile snapshot objects when no valid checkpoint remains.
-- Reject malformed three-field state shapes rather than reinterpreting them as legacy working memory, and contain failures while enumerating hostile branch entries.
-- Make canonical serialization and exported patch validation reject lossy or cyclic non-JSON inputs explicitly instead of returning invalid results or silently rewriting values.
+- `Documentation`: Add a task-first README quick start with explicit compatibility, opt-in behavior, one-off trial instructions, and Pi package security guidance.
+- `Protocol`: Tighten the normative runtime protocol and enforce a regression-tested character budget; omit absent validation feedback from synthetic runtime context instead of serializing a redundant `null`.
+- `Testing`: Redistribute lifecycle coverage from the former monolithic extension suite into the corresponding mirrored domain suites, leaving `extension.test.ts` focused on composition and using one shared test harness.
+- `Architecture`: Split the runtime into independent `json`, `state`, `episode`, `snapshot`, `session`, `recovery`, `status`, `context`, `skills`, `terminal`, `validation`, `transition`, and `extension` modules under `lib/`; isolate explicit episode transitions, active-branch selection and recovery, status rendering, bounded retry decisions, atomic state staging, and compare-and-swap commits; mirror each domain under `tests/`, enforce an acyclic dependency graph with cross-domain invariant tests, and reduce `index.ts` to composition and public exports.
+- `Lifecycle`: Register lifecycle commands in the canonical start, status, stop order.
+- `Context`: Centralize synthetic runtime-context construction and private validation-message filtering in the independently tested context domain, keeping user-controlled specifications out of system-prompt composition.
+- `Recovery`: Keep State Flow enabled and preserve the last committed state when terminal-validation retries are exhausted; only the transient retry chain is abandoned so the next user request can continue reliably.
+- `Skill`: Track Skill reads through an independently tested lifecycle correlator in Pi's actual `tool_execution_start` → `tool_call` event order while retaining the mutable intercepted input reference, so later argument rewrites are attributed to the executed path.
+- `Lifecycle`: Discard mismatched lifecycle records defensively so a stale or reused tool-call id cannot produce false Skill acquisition.
+- `Validation`: Bound restored iteration and validation-attempt counters before incrementing them, reject exhausted live iteration counters explicitly, and cover both safe-integer boundaries so malformed branch metadata cannot corrupt retry accounting or status output.
+- `Validation`: Reject restored non-JSON state values such as non-finite numbers before they can break hashing or silently materialize as `null`.
+- `Recovery`: Fall back past malformed newer checkpoints to the newest valid active-branch snapshot, while still failing closed on cyclic or hostile snapshot objects when no valid checkpoint remains.
+- `Recovery`: Reject malformed three-field state shapes rather than reinterpreting them as legacy working memory, and contain failures while enumerating hostile branch entries.
+- `Validation`: Make canonical serialization and exported patch validation reject lossy or cyclic non-JSON inputs explicitly instead of returning invalid results or silently rewriting values.
 
 ## 0.1.5: Skill attribution and state model clarification
 
-- Attribute successful Skill acquisition to finalized `tool_execution_start` arguments, with a tested compatibility fallback to the intercepted `tool_call` input.
-- Clarify that the three-field materialized handoff coexists with mutable exogenous project and runtime state that can also shape model behavior.
-- Remove the obsolete `/reload` step from the usage instructions.
+- `Skill`: Attribute successful Skill acquisition to finalized `tool_execution_start` arguments, with a tested compatibility fallback to the intercepted `tool_call` input.
+- `State`: Clarify that the three-field materialized handoff coexists with mutable exogenous project and runtime state that can also shape model behavior.
+- `Documentation`: Remove the obsolete `/reload` step from the usage instructions.
 
 ## 0.1.4: Release verification hotfix
 
-- Kept npm pack lifecycle output out of release inventory JSON so Trusted Publisher releases can complete public verification and GitHub Release creation.
+- `Release`: Kept npm pack lifecycle output out of release inventory JSON so Trusted Publisher releases can complete public verification and GitHub Release creation.
 
 ## 0.1.3: Trusted Publisher release automation
 
-- Added immutable-tag GitHub Actions automation that validates the package, publishes and verifies npm through Trusted Publisher with provenance, and creates the matching GitHub Release.
+- `Release`: Added immutable-tag GitHub Actions automation that validates the package, publishes and verifies npm through Trusted Publisher with provenance, and creates the matching GitHub Release.
 
 ## 0.1.2: Repository identity hotfix
 
-- Aligned GitHub repository, package metadata, installation documentation, and release links under the canonical `llblab/pi-state-flow` identity.
+- `Identity`: Aligned GitHub repository, package metadata, installation documentation, and release links under the canonical `llblab/pi-state-flow` identity.
 
 ## 0.1.1: Public npm distribution
 
-- Enabled public npm distribution for `@llblab/pi-state-flow`, including registry access and verified GitHub package metadata.
-- Clarified that compiled Skill knowledge is stored persistently under `contract.compiled_skills`, never as another top-level state field.
+- `Release`: Enabled public npm distribution for `@llblab/pi-state-flow`, including registry access and verified GitHub package metadata.
+- `Skill`: Clarified that compiled Skill knowledge is stored persistently under `contract.compiled_skills`, never as another top-level state field.
 
 ## 0.1.0
 
-- Added an opt-in State Flow runtime inspired by SKILL.state, with argument-free lifecycle commands, per-user-run specifications, active-branch persistence, and one materialized explicit state.
-- Added native Pi tool-loop preservation: tool-bearing responses require no patch, current-run tool trajectory remains model-visible, and one terminal handoff commits state after the complete agent run.
-- Added required flexible `contract` and `working` objects plus the required latest user-facing `response` string, recursive materialization, nested object-key `null` deletion, materialized-null rejection, and deterministic state compare-and-swap.
-- Kept arbitrary response content outside the transcript-private `<!-- state_flow … -->` memory-patch frame; the runtime strictly anchors the frame at the start of one terminal text block, requires exactly one blank separator, reconciles materialized `response` with Pi's finalized post-handler text at `turn_end`, and routes post-handler finalization failures through the same bounded hidden regeneration chain. Documented that the frame remains observable to streaming consumers before finalization.
-- Kept user-controlled turn specifications at user authority by moving their repeated representation out of the system prompt and into synthetic user runtime context, including support for empty text in image-only prompts.
-- Added active-branch restoration after `/tree` navigation, clean abandonment of interrupted terminal-validation retries before the next user run, and cumulative retry accounting across intervening tool-bearing turns.
-- Preserved persistent and current-run custom context from other Pi extensions, attributed Skill acquisition from finalized executed arguments after mutable tool interception, and limited accidental intermediate-envelope stripping to a structurally valid leading frame.
-- Hardened recursive patch materialization so JSON keys such as `__proto__` remain ordinary own data without changing object prototypes.
-- Added an explicit release file allowlist, Pi package discovery keywords, package-safe README targets, Pi/Node compatibility bounds, and a prepack validation gate so generated packages contain only runtime and human-facing release files.
-- Added bootstrap migration for enabling State Flow inside an existing session, per-run specification rotation, schema-free episode-level Skill compilation in `contract.compiled_skills` keyed by exact source path, and model-owned memory optimization that reorganizes inefficient structure and deletes stale, redundant, speculative, or low-value state.
-- Removed per-tool state commits, action authorization, Delta Window, observation envelopes, action ledgers, project schemas, state and patch byte caps, dynamic growth pressure, and all coupling to other extensions.
-- Compressed the static runtime protocol while retaining terminal, handoff, Skill-compilation, authority, and memory-optimization invariants.
-- Added stop-as-complete-episode-reset semantics, a compact accent `state-flow` plus dim `#<iteration>` status, and complete pretty-formatted state JSON output from `/state-flow-status`.
+- `Runtime`: Added an opt-in State Flow runtime inspired by SKILL.state, with argument-free lifecycle commands, per-user-run specifications, active-branch persistence, and one materialized explicit state.
+- `Lifecycle`: Added native Pi tool-loop preservation: tool-bearing responses require no patch, current-run tool trajectory remains model-visible, and one terminal handoff commits state after the complete agent run.
+- `State`: Added required flexible `contract` and `working` objects plus the required latest user-facing `response` string, recursive materialization, nested object-key `null` deletion, materialized-null rejection, and deterministic state compare-and-swap.
+- `Terminal`: Kept arbitrary response content outside the transcript-private `<!-- state_flow … -->` memory-patch frame; the runtime strictly anchors the frame at the start of one terminal text block, requires exactly one blank separator, reconciles materialized `response` with Pi's finalized post-handler text at `turn_end`, and routes post-handler finalization failures through the same bounded hidden regeneration chain. Documented that the frame remains observable to streaming consumers before finalization.
+- `Authority`: Kept user-controlled turn specifications at user authority by moving their repeated representation out of the system prompt and into synthetic user runtime context, including support for empty text in image-only prompts.
+- `Recovery`: Added active-branch restoration after `/tree` navigation, clean abandonment of interrupted terminal-validation retries before the next user run, and cumulative retry accounting across intervening tool-bearing turns.
+- `Context`: Preserved persistent and current-run custom context from other Pi extensions, attributed Skill acquisition from finalized executed arguments after mutable tool interception, and limited accidental intermediate-envelope stripping to a structurally valid leading frame.
+- `State`: Hardened recursive patch materialization so JSON keys such as `__proto__` remain ordinary own data without changing object prototypes.
+- `Packaging`: Added an explicit release file allowlist, Pi package discovery keywords, package-safe README targets, Pi/Node compatibility bounds, and a prepack validation gate so generated packages contain only runtime and human-facing release files.
+- `Bootstrap`: Added bootstrap migration for enabling State Flow inside an existing session, per-run specification rotation, schema-free episode-level Skill compilation in `contract.compiled_skills` keyed by exact source path, and model-owned memory optimization that reorganizes inefficient structure and deletes stale, redundant, speculative, or low-value state.
+- `Architecture`: Removed per-tool state commits, action authorization, Delta Window, observation envelopes, action ledgers, project schemas, state and patch byte caps, dynamic growth pressure, and all coupling to other extensions.
+- `Protocol`: Compressed the static runtime protocol while retaining terminal, handoff, Skill-compilation, authority, and memory-optimization invariants.
+- `Lifecycle`: Added stop-as-complete-episode-reset semantics, a compact accent `state-flow` plus dim `#<iteration>` status, and complete pretty-formatted state JSON output from `/state-flow-status`.