@llblab/pi-state-flow 0.4.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/AGENTS.md CHANGED
@@ -10,7 +10,7 @@
10
10
  - 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 hash/compiler fields, and attach the runtime-observed source hash plus current ordinary compiler revision before publication. Compile routing descriptions by default, never raw Markdown or a full-file summary; preserve uncertainty and reserve richer compilations for reusable operational semantics.
11
11
  - 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.
12
12
  - 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.
13
- - Load optional agent-level `state-flow.json` from Pi's configured agent directory once per extension load/reload. Its `directory` selects the state store (default `agentDir/state-flow`; relative paths resolve from the config directory, `~/` from HOME); `autoStart` defaults false and governs only genuinely new sessions. Explicit SDK `repositoryRoot` overrides the configured directory; SDK `agentDir` selects the profile and `knowledgeRoot` remains independent. Reject invalid config before registration/writes, never relocate or rewrite it with state, and preserve branch-local enablement on resume/tree/stop.
13
+ - Load optional agent-level `state-flow.json` once per extension load/reload. Its `directory` selects the state store, `autoStart` defaults false for genuinely new sessions, and `remotePublication` selects `off`, `turn-end`, or compatibility `transition`. State Flow always owns durable memory while enabled and global semantic memory is always available; these are invariants, not configuration switches. Keep runtime configuration and provenance outside model-patchable semantic state.
14
14
  - Keep runtime configuration and provenance separate from model-patchable semantic state. Persist session `config.json` for enablement/projection settings and `meta.json` for lineage, counters, branch identity, durable base, publication, and migration metadata. Neither participates in scope overlay. 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 formats are read-only migration input. 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, so stop or lifecycle persistence does not rewind another branch's live files. 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.
15
15
  - 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.
16
16
  - Reserve `state` for the runtime materialized semantic view. For each scope, current state is exactly `materialize(checkpoint.json, patches.jsonl)`: 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.
@@ -19,14 +19,14 @@
19
19
  - 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` exposes one cached effective/global/CWD/session projection at offset 0–7, defaulting to effective/0; it returns the exact boundary with semantic state and never publishes, appends a checkpoint, or advances 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.
20
20
  - 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` and `patches.jsonl` for global; `<cwd-key>/checkpoint.json` and `<cwd-key>/patches.jsonl` for CWD; `<cwd-key>/<session-key>/checkpoint.json`, `patches.jsonl`, `config.json`, and `meta.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 checkpoint ownership to fail closed on Pi-name collisions.
21
21
  - Migrate legacy current `state.json` losslessly into an initial anchored checkpoint with an empty tail; current snapshots are the sole semantic recovery basis, independent of the presence or validity of explanatory journals, including historical revision reads. Preserve only proven history, remove obsolete files within the successful scoped migration, and never retain two authoritative formats. Exercise migrations in temporary repositories rather than modifying the user's active Knowledge data during development.
22
- - 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; never use repository-wide staging. Retain opaque source bytes for file identity and rollback, not decoded-text reconstructions. 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.
22
+ - 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; never use repository-wide staging. 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.
23
23
  - 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. 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.
24
24
  - 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.
25
- - Every accepted semantic change, including session-only and response-only changes, atomically updates affected checkpoint/tail pairs and corresponding temporal metadata, persists one accepted cohort immediately. With Git available and initialized, create one Git commit per accepted semantic cohort and attempt a push when a remote is configured; do not batch intermediate patches until turn end. A repository with no remote is intentionally local-only, not a failed publication. If the Git executable is absent, persist files without Git operations or fake Git revisions/pending pushes. Operational Git failures are not evidence that Git is absent. A multi-scope cohort uses one identity and one consistent commit. Ensure the committed tree contains the selected cohort, not merely matching live files: initialize/adopt uncommitted streams explicitly, preserve exact unchanged scope bytes, and reject omitted uncommitted scopes. File-to-Git adoption must prove the current file reference before writing, preserve semantic step/lineage, and install the Git basis only after successful publication. Construct commits through an isolated index, compare-and-swap the reconciled base, align only owned entries in the caller's index, and preserve unrelated staged and dirty files. A local commit accepts the transition; push failure is pending publication, must not trigger terminal regeneration, must survive durable runtime metadata across restart, and retries must push the existing commit without duplicating the semantic transition. Git owns complete cold history for Git-backed transitions; file-only mode retains current materialization and proven hot history, not a second unbounded store. Restore file pointers only while their exact cohort is available, and report unavailable old state rather than adopting current files as the selected past. Installing Git must preserve file-only state when initializing the repository; cold Git history begins at that adoption, without fabricating earlier commits. Keep the untagged pre-0.4 SHA-suffixed layout read-only at historical Git revisions; migrate a current matching CWD/session cohort once to Pi-native paths under publication exclusion, and persist the replacement pointer immediately when that cohort is the selected HEAD.
26
- - Register `patch_state` as the sole semantic mutation tool. It applies one validated `session`, `cwd`, or `global` semantic patch immediately through temporal folding/publication, records the accepted lineage and durable revision, returns a compact acknowledgement, and makes the next inference receive the new `state[0]`; the previous state becomes `state[1]`. Use it only for established future-relevant state whose delayed materialization creates meaningful loss or recovery risk, never scratchpad, narration, routine progress, or speculative churn.
25
+ - 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. `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; use exact targets, destination identity, symlink-safe atomic CAS, descendant-only coalescing, cross-process worker leases, restart recovery, and truthful failure diagnostics. 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.
26
+ - Register `patch_state` as the sole semantic mutation tool. It applies one validated `session`, `cwd`, or `global` semantic patch immediately through temporal folding/publication, records the accepted lineage and durable revision, returns a compact acknowledgement, and makes the next inference receive the new `state[0]`; the previous state becomes `state[1]`. Use it for established future-relevant state whose delayed materialization creates meaningful loss or recovery risk, or for a necessary write-and-verify step in explicitly requested curation; never use it for scratchpad, narration, routine progress, or speculative churn.
27
27
  - Treat `patch_state` as a strict inference barrier. Give it sequential execution mode, inspect Pi's synchronized current assistant message during tool preflight, require exactly one `patch_state` call in that response, and block every sibling tool call before execution. After success, retain the tool call/result as current-run causality and let the model choose all subsequent actions from rematerialized context.
28
28
  - Require exactly one terminal reconciliation after zero or more intermediate barriers in every successful enabled run. Accept a non-empty ordinary terminal answer without a State Flow comment as an empty model patch: preserve `artifacts`, `contract`, and `working`, replace session `response`, and persist that session semantic change through the same Git lifecycle. Explicit comment markers (including malformed or embedded ones) must not silently fall back to ordinary text. When a patch is present, require one top-level transcript-private `<!-- state_flow … -->` comment containing exactly a `transitions` array, one separating blank line, then the user-facing answer exactly once. Each transition must contain one unique known `scope` and an object `patch` limited to `artifacts`, `contract`, and `working`; reject model-authored `response`, runtime `config`, or provenance. Retain pre-scoped three-field envelopes only as session compatibility shorthand. At `message_end`, remove the comment and stage every affected scope against semantic hashes and the actual active causal-boundary identity, so equal values cannot authorize crossing to another lineage; at `turn_end`, reconcile session `response` with Pi's finalized assistant message after all chained handlers, atomically publish every affected checkpoint/tail pair and temporal metadata in one commit, and record its revision in the branch checkpoint. Do not write materially unchanged non-session scopes. Route missing text or a tool call added after terminal validation through the same bounded regeneration chain. Transcript-private does not mean confidential during streaming.
29
- - Treat terminal state as a decision-relevant handoff, not narration: retain source-addressed reusable operational knowledge in `artifacts`; compile stable requirements, decisions, rejected approaches, and interface commitments into `contract`; retain verified facts, validation, failures, current domain state, unresolved work, and exact continuation in `working`.
29
+ - 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.
30
30
  - 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. 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.
31
31
  - 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.
32
32
  - 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 at the next intermediate or terminal CWD transition under `patch.artifacts[exactReadPath]` with `description`, `kind: "skill"`, and a flexible non-empty `compilation` object; hash the executed source bytes and attach runtime-owned `hash` plus `skill-artifact-v1` compiler metadata; reject missing, unhashable, malformed, or forged freshness data; replace the complete prior Skill artifact on refresh so obsolete metadata 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.
package/BACKLOG.md CHANGED
@@ -1,15 +1,126 @@
1
1
  # BACKLOG
2
2
 
3
- Canonical open work for **pi-state-flow**. [README.md](README.md) explains setup and behavior; [AGENTS.md](AGENTS.md) governs implementation.
3
+ Canonical proposed work for **pi-state-flow 0.6.0 — Continuity without fixation**.
4
4
 
5
- ## Open work
5
+ 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.
6
6
 
7
- No open work remains in the dedicated-store, optional-Git, and agent-configuration scope. [CHANGELOG.md](CHANGELOG.md) records delivery; the [acceptance map](docs/temporal-acceptance.md) identifies executable witnesses and verification limits.
7
+ ## Release contract
8
8
 
9
- ## Boundaries
9
+ 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.
10
10
 
11
- - Preserve unrelated repository work; source commits, publication, and release require their own scope.
12
- - Exercise migrations and backend adoption in temporary repositories, not production Knowledge or state data.
13
- - File-only mode retains current/hot state, not arbitrary cold branches; unavailable exact references never authorize substituting current files for selected history.
14
- - Changing the configured directory selects a store; it does not automatically migrate previous files or Git history.
15
- - Knowledge semantics, automatic semantic branch merging, a second unbounded history store, and eager historical snapshot injection remain excluded.
11
+ 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.
12
+
13
+ **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.
14
+
15
+ ## Fixed boundaries
16
+
17
+ - Keep the semantic shape exactly `artifacts`, `contract`, `working`, `response`, with existing flexible object contents and `global → cwd → session` overlay.
18
+ - Preserve `checkpoint.json` / `patches.jsonl`, shared causal boundaries, hot offsets 0–7, Git/file-only guarantees, branch restoration, and local acceptance versus remote publication.
19
+ - 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.
20
+ - Keep `patch_state` single-scope and the sole semantic mutation tool. Keep terminal multi-scope reconciliation, runtime-owned response, and strict inference barriers.
21
+ - No required per-item confidence/provenance/status schema, additional memory store, semantic truth validator, automatic curation, state-size gate, or mandatory historical/source reread.
22
+ - No automatic permission expansion, external publication, or historical erasure. Scope is applicability, not instruction authority.
23
+ - No blockchain/IPFS/JAM integration, model marketplace, speculative alternate-agent execution, or native auto-resume work in this release.
24
+
25
+ ## Ordered work
26
+
27
+ ### [x] SF-060-01 — Make ordinary runtime handoffs preserve continuity without fixing the method
28
+
29
+ **Primary files:** `lib/terminal.ts`, `lib/extension.ts`, `tests/terminal.test.ts`. Align normative wording in `AGENTS.md`.
30
+
31
+ 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.
32
+
33
+ Required semantics:
34
+
35
+ - 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.
36
+ - 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.
37
+ - 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.
38
+ - 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.
39
+ - 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.
40
+ - Preserve completed prerequisites and verified outcomes that remain relevant; remove obsolete progress narration, not the fact that work was completed.
41
+ - 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.
42
+ - Keep `working` as last observations, not live external state. Preserve targeted revalidation needs without promising rollback or exactly-once effects.
43
+ - 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.
44
+
45
+ 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.
46
+
47
+ **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.
48
+
49
+ ### [x] SF-060-02 — Ship the revised bounded curation Skill
50
+
51
+ **Primary files:** `skills/state-flow-memory/SKILL.md`, `tests/skills.test.ts`.
52
+
53
+ 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.
54
+
55
+ Required outcomes:
56
+
57
+ - Add `reframe` alongside keep/update/narrow/promotion/remove. These are audit choices, not mandatory stored labels.
58
+ - Preserve useful uncertainty, commitments, interaction consequences, bounded learning, source recoverability, and the distinction between a requirement and a provisional method.
59
+ - 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.
60
+ - 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.
61
+ - 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.
62
+ - 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.
63
+ - 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.
64
+
65
+ **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.
66
+
67
+ ### [x] SF-060-03 — Prove the Skill can complete curation through existing barriers
68
+
69
+ **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.
70
+
71
+ 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.
72
+
73
+ Document and regression-test this executable sequence:
74
+
75
+ 1. Read the curation Skill when needed; accept its required CWD compilation before accumulating a global compilation obligation.
76
+ 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.
77
+ 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.
78
+ 4. Complete one terminal reconciliation without repeating already accepted compilations or inventing memory changes.
79
+
80
+ 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.
81
+
82
+ Cover these boundaries:
83
+
84
+ - A Skill read followed by an unrelated session/global patch without required compilation is rejected without accepting state; the documented compilation-first route succeeds.
85
+ - 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.
86
+ - 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.
87
+ - 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.
88
+ - No-op memory curation introduces no fabricated memory changes. A changed final response may still create a semantic transition under the existing contract.
89
+ - Reader siblings remain blocked by `patch_state`; read-only verification creates no transition. A successful local acceptance is not repeated because remote replication failed.
90
+
91
+ **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.
92
+
93
+ ### [x] SF-060-05 — Align documentation, preserve compatibility, and prepare release
94
+
95
+ **Primary files:** `AGENTS.md`, `README.md`, `docs/architecture.md`, `CHANGELOG.md`, `package.json`, `package-lock.json`, and this backlog.
96
+
97
+ - Describe ordinary handoff versus explicit curation consistently, including useful uncertainty, confirmed decisions, bounded negative results and interaction consequences.
98
+ - 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.
99
+ - Document compilation-first curation scheduling and the existing mixed-acquisition limitation. Do not advertise a new atomic multi-scope tool operation.
100
+ - 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.
101
+ - 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.
102
+ - 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.
103
+
104
+ **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.
105
+
106
+ ## Dependencies and stopping rule
107
+
108
+ `SF-060-01 → SF-060-02 → SF-060-03`; `SF-060-05` closes the release.
109
+
110
+ 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.
111
+
112
+ 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.
113
+
114
+ ## Deferred host integration — preserved from 0.5.0
115
+
116
+ - [ ] **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.
117
+
118
+ ## Baseline evidence
119
+
120
+ The findings above come from inspection of this pinned revision, not an execution of its tests:
121
+
122
+ - [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.
123
+ - [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.
124
+ - [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.
125
+ - [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.
126
+ - [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/CHANGELOG.md CHANGED
@@ -1,103 +1,121 @@
1
1
  # Changelog
2
2
 
3
- ## Unreleased
3
+ > Each release keeps at most 8 outcome records of at most 512 characters.
4
+
5
+ ## 0.6.0: Continuity without fixation
6
+
7
+ - `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.
8
+ - `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.
9
+ - `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.
10
+ - `Compatibility`: Preserved the 0.5.0 semantic shape and Git/file storage without migration, bulk rewrite, new dependency, or new runtime/config/tool contract.
11
+
12
+ ## 0.5.0: Durable memory, compiled routing, and local-first publication
13
+
14
+ - `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.
15
+ - `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.
16
+ - `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.
17
+ - `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.
18
+ - `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.
19
+ - `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.
20
+ - `Transcript`: Restored the empty-line boundary between the `patch_state` tool call and its materialization result in Pi and Telegram transcript rendering.
21
+ - `Skill`: Bundled the optional `state-flow-memory` Skill for explicit bounded audits, scope narrowing, contradiction cleanup, and evidence-gated external handoff without background maintenance.
4
22
 
5
23
  ## 0.4.0: Temporal state and independent durable storage
6
24
 
7
25
  ### Temporal state
8
26
 
9
- - 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.
10
- - 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.
11
- - 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.
27
+ - `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.
28
+ - `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.
29
+ - `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.
12
30
 
13
31
  ### Storage and recovery
14
32
 
15
- - 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.
16
- - 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.
17
- - 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.
18
- - 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.
19
- - 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.
33
+ - `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.
34
+ - `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.
35
+ - `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.
36
+ - `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.
37
+ - `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.
20
38
 
21
39
  ### Configuration, context, and diagnostics
22
40
 
23
- - 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.
24
- - 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.
25
- - 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.
41
+ - `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.
42
+ - `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.
43
+ - `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.
26
44
 
27
45
  ## 0.3.0: Optional memory patches and evidence-aware handoffs
28
46
 
29
- - 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.
30
- - 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.
31
- - 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.
32
- - Keep malformed explicit envelopes and missing Skill compilations on the existing bounded validation path.
33
- - Clear the backlog; documented integration and continuation-quality limitations remain, not release commitments.
47
+ - `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.
48
+ - `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.
49
+ - `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.
50
+ - `Validation`: Keep malformed explicit envelopes and missing Skill compilations on the existing bounded validation path.
51
+ - `Planning`: Clear the backlog; documented integration and continuation-quality limitations remain, not release commitments.
34
52
 
35
53
  ## 0.2.3: Document protocol and validation limitations
36
54
 
37
- - 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.
38
- - Clarify that mock lifecycle tests are not real Pi scheduler integration checks and that structural validation cannot guarantee semantic memory retention.
39
- - No runtime behavior changes.
55
+ - `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.
56
+ - `Validation`: Clarify that mock lifecycle tests are not real Pi scheduler integration checks and that structural validation cannot guarantee semantic memory retention.
57
+ - `Runtime`: No runtime behavior changes.
40
58
 
41
59
  ## 0.2.2: README structure hotfix
42
60
 
43
- - Separate installation from usage, remove the redundant quick-start section, and move architecture details after the user-facing documentation.
61
+ - `Documentation`: Separate installation from usage, remove the redundant quick-start section, and move architecture details after the user-facing documentation.
44
62
 
45
63
  ## 0.2.1: README banner hotfix
46
64
 
47
- - Add the project banner to the README.
65
+ - `Documentation`: Add the project banner to the README.
48
66
 
49
67
  ## 0.2.0: Modular runtime hardening
50
68
 
51
- - Add a task-first README quick start with explicit compatibility, opt-in behavior, one-off trial instructions, and Pi package security guidance.
52
- - 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`.
53
- - 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.
54
- - 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.
55
- - Register lifecycle commands in the canonical start, status, stop order.
56
- - 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.
57
- - 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.
58
- - 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.
59
- - Discard mismatched lifecycle records defensively so a stale or reused tool-call id cannot produce false Skill acquisition.
60
- - 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.
61
- - Reject restored non-JSON state values such as non-finite numbers before they can break hashing or silently materialize as `null`.
62
- - 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.
63
- - Reject malformed three-field state shapes rather than reinterpreting them as legacy working memory, and contain failures while enumerating hostile branch entries.
64
- - Make canonical serialization and exported patch validation reject lossy or cyclic non-JSON inputs explicitly instead of returning invalid results or silently rewriting values.
69
+ - `Documentation`: Add a task-first README quick start with explicit compatibility, opt-in behavior, one-off trial instructions, and Pi package security guidance.
70
+ - `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`.
71
+ - `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.
72
+ - `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.
73
+ - `Lifecycle`: Register lifecycle commands in the canonical start, status, stop order.
74
+ - `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.
75
+ - `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.
76
+ - `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.
77
+ - `Lifecycle`: Discard mismatched lifecycle records defensively so a stale or reused tool-call id cannot produce false Skill acquisition.
78
+ - `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.
79
+ - `Validation`: Reject restored non-JSON state values such as non-finite numbers before they can break hashing or silently materialize as `null`.
80
+ - `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.
81
+ - `Recovery`: Reject malformed three-field state shapes rather than reinterpreting them as legacy working memory, and contain failures while enumerating hostile branch entries.
82
+ - `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.
65
83
 
66
84
  ## 0.1.5: Skill attribution and state model clarification
67
85
 
68
- - Attribute successful Skill acquisition to finalized `tool_execution_start` arguments, with a tested compatibility fallback to the intercepted `tool_call` input.
69
- - Clarify that the three-field materialized handoff coexists with mutable exogenous project and runtime state that can also shape model behavior.
70
- - Remove the obsolete `/reload` step from the usage instructions.
86
+ - `Skill`: Attribute successful Skill acquisition to finalized `tool_execution_start` arguments, with a tested compatibility fallback to the intercepted `tool_call` input.
87
+ - `State`: Clarify that the three-field materialized handoff coexists with mutable exogenous project and runtime state that can also shape model behavior.
88
+ - `Documentation`: Remove the obsolete `/reload` step from the usage instructions.
71
89
 
72
90
  ## 0.1.4: Release verification hotfix
73
91
 
74
- - Kept npm pack lifecycle output out of release inventory JSON so Trusted Publisher releases can complete public verification and GitHub Release creation.
92
+ - `Release`: Kept npm pack lifecycle output out of release inventory JSON so Trusted Publisher releases can complete public verification and GitHub Release creation.
75
93
 
76
94
  ## 0.1.3: Trusted Publisher release automation
77
95
 
78
- - 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.
96
+ - `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.
79
97
 
80
98
  ## 0.1.2: Repository identity hotfix
81
99
 
82
- - Aligned GitHub repository, package metadata, installation documentation, and release links under the canonical `llblab/pi-state-flow` identity.
100
+ - `Identity`: Aligned GitHub repository, package metadata, installation documentation, and release links under the canonical `llblab/pi-state-flow` identity.
83
101
 
84
102
  ## 0.1.1: Public npm distribution
85
103
 
86
- - Enabled public npm distribution for `@llblab/pi-state-flow`, including registry access and verified GitHub package metadata.
87
- - Clarified that compiled Skill knowledge is stored persistently under `contract.compiled_skills`, never as another top-level state field.
104
+ - `Release`: Enabled public npm distribution for `@llblab/pi-state-flow`, including registry access and verified GitHub package metadata.
105
+ - `Skill`: Clarified that compiled Skill knowledge is stored persistently under `contract.compiled_skills`, never as another top-level state field.
88
106
 
89
107
  ## 0.1.0
90
108
 
91
- - 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.
92
- - 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.
93
- - 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.
94
- - 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.
95
- - 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.
96
- - 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.
97
- - 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.
98
- - Hardened recursive patch materialization so JSON keys such as `__proto__` remain ordinary own data without changing object prototypes.
99
- - 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.
100
- - 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.
101
- - 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.
102
- - Compressed the static runtime protocol while retaining terminal, handoff, Skill-compilation, authority, and memory-optimization invariants.
103
- - 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`.
109
+ - `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.
110
+ - `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.
111
+ - `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.
112
+ - `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.
113
+ - `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.
114
+ - `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.
115
+ - `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.
116
+ - `State`: Hardened recursive patch materialization so JSON keys such as `__proto__` remain ordinary own data without changing object prototypes.
117
+ - `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.
118
+ - `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.
119
+ - `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.
120
+ - `Protocol`: Compressed the static runtime protocol while retaining terminal, handoff, Skill-compilation, authority, and memory-optimization invariants.
121
+ - `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`.
package/README.md CHANGED
@@ -37,12 +37,14 @@ Optional `~/.pi/agent/state-flow.json` (or `state-flow.json` beneath `PI_CODING_
37
37
  ```json
38
38
  {
39
39
  "directory": "~/.pi/agent/state-flow",
40
- "autoStart": false
40
+ "autoStart": false,
41
+ "remotePublication": "turn-end"
41
42
  }
42
43
  ```
43
44
 
44
45
  - `directory`: State storage location; omitted defaults to `state-flow/` beneath Pi's agent directory. Absolute paths, `~`/`~/` and relative paths are supported; relative paths resolve from the configuration directory, not the project CWD.
45
46
  - `autoStart`: Set to `true` to enable State Flow automatically for genuinely new sessions, including fresh CWDs. Omitted defaults to `false`: manual activation, even when previous CWD materialization exists.
47
+ - `remotePublication`: For new runtimes, `turn-end` (default) queues one newest target after local acceptance and pushes asynchronously; `off` keeps commits local; `transition` preserves legacy synchronous push behavior. A resumed branch keeps its persisted policy.
46
48
 
47
49
  Configuration is read at extension load; edit it and use `/reload` (or restart Pi) before opening a new session. Existing branches retain their stored enablement on resume/tree navigation. `/state-flow-stop` does not rewrite this file or disable automatic mode for later new sessions. Invalid JSON, unknown keys or invalid values fail extension loading rather than silently choosing another directory. A missing file uses defaults and is not generated automatically.
48
50
 
@@ -229,7 +231,7 @@ Artifacts use exact source paths as keys. Minimum metadata is:
229
231
  {"description":"What this source contains and when it is useful","hash":"sha256:<64 lowercase hex characters>","compiler":"artifact-v1"}
230
232
  ```
231
233
 
232
- Descriptions and compiler revisions are non-empty; hashes are canonical lowercase SHA-256. Optional `kind`, `compiled_at`, and `compilation` are validated when present, while unknown JSON metadata remains forward-compatible. Ordinary artifacts need no `kind`. Hash plus compiler revision determines freshness, not `compiled_at`.
234
+ Descriptions and compiler revisions are non-empty; hashes are canonical lowercase SHA-256. Optional `kind`, `compiled_at`, `compilation`, and `tags` are validated when present, while arbitrary unknown finite non-null JSON metadata remains forward-compatible. Tags are unique non-empty trimmed strings; `selectArtifactsByTags` provides deterministic all/any candidate filtering, but a tag match never authorizes source acquisition. Ordinary artifacts need no `kind` or tags. Hash plus compiler revision determines freshness, not `compiled_at`.
233
235
 
234
236
  Session initialization generically discovers regular lowercase `*.md` beneath the independent canonical Knowledge source root, normally `~/.pi/agent/knowledge` (or `knowledge/` beneath the agent directory selected by `PI_CODING_AGENT_DIR`). This source directory need not be a Git repository. Discovery hashes opaque bytes and retains byte counts without decoding or storing bodies; it skips symlinks and never escapes the root. A missing root means no candidates. Root and nested Markdown are treated alike, without reserved names, frontmatter parsing, validators, templates, or a `save_knowledge` implementation/call. Arbitrary repository files remain independent from State Flow.
235
237
 
@@ -239,21 +241,27 @@ Default compilation is a compact routing description, not raw Markdown or a full
239
241
 
240
242
  ### Materialized-first policy
241
243
 
242
- Read a source only for a concrete relevant gap not covered by sufficient compilation, an exact-source operation including edits, evidenced invalidation, contradiction/failure reconciliation, explicit request, or bounded maintenance selection. New sessions, routine recall/activation, reassurance, and a description/index alone are not reasons to reread. Changed hashes require reacquisition; prefer the smallest sufficient read. Semantic sufficiency is caller-assessed, not proven by the existence of a compilation field.
244
+ Read a source only for a concrete relevant gap not covered by sufficient compilation, an exact-source operation including edits, evidenced invalidation, contradiction/failure reconciliation, explicit request, or bounded maintenance selection. The explicit rehydration planner binds scope, path, candidate hash, and reason, then reuses Pi's visible native `read`; State Flow does not register a duplicate artifact-reading tool. New sessions, routine recall/activation, reassurance, and a description/index alone are not reasons to reread. Changed hashes require reacquisition; prefer the smallest sufficient read. Semantic sufficiency is caller-assessed, not proven by the existence of a compilation field.
243
245
 
244
246
  Optional `planArtifactMaintenance` selects only otherwise-fresh old artifacts, ranking missing/unparseable timestamps first, then oldest `compiled_at` and path. Defaults admit at most one source and 16 KiB after 30 days. Strict count/byte ceilings can be zero; source bytes conservatively bound tokenizer input. The planner never reads, compiles, or modifies sources. Correctness invalidation takes precedence; explicit full refresh is separate from maintenance budgets and never an automatic startup rebuild.
245
247
 
246
248
  ### Skill compilation
247
249
 
248
- Every successful `SKILL.md` read requires CWD compiler output at the exact executed path at the next barrier or terminal transition, with non-empty `description`, `kind: "skill"`, and a non-empty flexible `compilation` object. Compile applicability, routing, constraints, and failure conditions rather than source text. Runtime attaches the executed byte hash and `skill-artifact-v1`; missing/unhashable/forged freshness or missing compilation fails validation. Refresh replaces the complete old artifact, including obsolete metadata.
250
+ Every successful `SKILL.md` read requires CWD compiler output at the exact executed path at the next barrier or terminal transition, with non-empty `description`, `kind: "skill"`, and a non-empty flexible `compilation` object. Compile applicability, routing, constraints, and failure conditions rather than source text. Runtime attaches the executed byte hash and `skill-artifact-v1`; missing/unhashable/forged freshness or missing compilation fails validation. Matching metadata proves source-version consistency, not semantic fidelity, truth, or higher instruction authority. Refresh replaces the complete old artifact, including obsolete metadata.
249
251
 
250
252
  Correlation follows finalized mutable `tool_call` arguments with execution-start compatibility fallback. Legacy `contract.compiled_skills` entries migrate into artifacts, preserving behavior and marking unavailable-source fallback hashes unverified. New patches cannot recreate the retired store.
251
253
 
254
+ ### Optional memory curation
255
+
256
+ The package includes the progressively disclosed `state-flow-memory` Skill for explicit audits, contradiction cleanup, scope narrowing, stale continuation review, and ownership migration. It is not part of routine retention and never runs as background maintenance. The Skill preserves useful uncertainty, confirmed decisions, bounded results, interaction consequences, and completed prerequisites without fixing provisional methods. Its compilation-first sequence writes and separately verifies a destination before source deletion, then inspects the effective overlay; separate single-scope calls are not atomic migration. External promotion cannot delete the only accepted copy without destination identity, content, and revision evidence. State Flow remains the memory owner and global memory remains available throughout.
257
+
258
+ External handoffs may use the generic global `working.memory_promotions` map. Each entry requires `status` (`pending`, `accepted`, `failed`, or `unknown`) and a non-empty `owner`; accepted entries additionally require an exact destination `pointer` and `revision`. Other fields remain forward-compatible and destination-specific. This bookkeeping does not replace the retained candidate: failures and uncertainty keep the accepted State Flow body plus exact continuation, while proven acceptance may remove the duplicate body and retain the compact pointer record. `/state-flow-status` reports owner mode, fallback activation, memory-bearing scopes, promotion counts, and bounded pointer/error details; malformed or incompletely evidenced accepted records appear as invalid rather than accepted.
259
+
252
260
  ## Handoff quality and external reality
253
261
 
254
- A terminal handoff is decision-relevant memory, not narration. Preserve active constraints, unresolved questions, consequential negative results, and the next discriminating check before compression. Keep user requirements, observations, assistant decisions, and hypotheses distinct. Retain useful source locators, validity conditions, rejection reasons, and reconsideration conditions. Reconcile contradictions with evidence or user clarification; preserve unresolved conflicts as uncertain.
262
+ A terminal handoff is decision-relevant memory, not narration. Preserve active commitments, confirmed decisions, relevant interaction consequences, bounded results, unresolved questions, and the exact continuation. Keep user requirements, observations, assistant conclusions, provisional methods, and hypotheses distinct; silence is not acceptance. Retain useful evidence locators, validity conditions, exact rejection reasons, and known reconsideration conditions. A failed mechanism does not disprove every implementation, and one success does not establish unrestricted validity. Reconcile contradictions with evidence or user clarification; preserve decision-relevant conflicts and hypotheses explicitly as uncertain.
255
263
 
256
- At every handoff audit complete state: merge fragmented facts, compress history into conclusions, reorganize inefficient structure, and delete stale, completed, redundant, or low-value keys without losing active commitments and evidence. Do not invent bookkeeping merely to cause a transition. Structural validators cannot prove semantic usefulness or compilation fidelity; fresh-agent continuation tests provide behavioral evidence.
264
+ At every handoff reconcile information affected by the run and relevant existing commitments, not every repository or scope. Merge fragmented facts and delete stale, redundant, unsupported, or obsolete progress narration without losing completed prerequisites, active commitments, or evidence. Do not invent bookkeeping merely to cause a transition. Structural validators cannot prove semantic usefulness or compilation fidelity; fresh-agent continuation tests provide behavioral evidence.
257
265
 
258
266
  `working` contains last observations, not live reality. Revalidate volatile facts before consequential actions. After interruption or branch restoration, inspect relevant external effects before repeating operations. A failed commit does not undo tools; restored memory does not restore the workspace. Missing evidence proves neither success nor absence of effects. Preserve uncertainty and the next check rather than adding action ledgers or claiming rollback/exactly-once guarantees.
259
267
 
@@ -267,7 +275,7 @@ State, the active specification, current trajectory, and external full trace hav
267
275
 
268
276
  ## Architecture and validation
269
277
 
270
- See the [documentation index](docs/README.md) and [twenty temporal acceptance properties](docs/temporal-acceptance.md) for the requirement-to-test map and verification limits.
278
+ See the [documentation index](docs/README.md), [continuity acceptance map](docs/continuity-acceptance.md), and [twenty temporal acceptance properties](docs/temporal-acceptance.md) for requirement-to-test maps and verification limits.
271
279
 
272
280
  `index.ts` remains composition/public exports only. Flat independent `lib/` domains own their responsibilities: `temporal` owns anchored streams, folding, active-lineage validation, and lazy historical algebra; `durable` owns exact files; `git` owns revision/CAS publication; `history` owns compact transition records; `state` owns semantic shape/overlay; `transition` coordinates accepted patches; `snapshot`, `session`, `recovery`, and `episode` own runtime/branch lifecycle; `context`, `status`, `terminal`, and `validation` own projection and finalization; artifact domains own discovery/acquisition/compilation/maintenance; `extension` composes Pi integration. `runtime` caches branch-selected streams and their publication basis beneath the Pi adapter; `config` owns read-only agent-level settings independently from branch runtime configuration. Predecessor current-state/journal writers are test-only; production retains explicit migration readers, and Pi checkpoints carry revision pointers.
273
281
 
package/docs/README.md CHANGED
@@ -1,6 +1,4 @@
1
1
  # State Flow documentation
2
2
 
3
+ - [Architecture](architecture.md): Semantic state, temporal algebra, Pi lifecycle, storage, optional Git, asynchronous publication, artifact routing, durable memory, and session-continuation boundaries.
3
4
  - [Temporal acceptance](temporal-acceptance.md): The twenty required temporal properties and their executable witnesses.
4
- - [Package guide](../README.md): Installation, state model, runtime controls, storage, and development.
5
-
6
- Open work belongs only in [BACKLOG.md](../BACKLOG.md); these documents describe contracts and evidence routes.