@llblab/pi-kit 0.15.0 → 0.17.0

package/node_modules/@llblab/pi-state-flow/dist/skills/state-flow-memory/SKILL.md

@@ -1,138 +1,40 @@
 ---
 name: state-flow-memory
-description: Audit and reconcile State Flow durable memory across global, CWD, and session scopes. Preserve commitments, established learning, and the point of continuation without freezing provisional approaches. Use after completing a major feature, important release, large body of work, campaign, project phase, or meaningful checkpoint—even when the user did not explicitly ask for memory work—as well as for explicit memory curation, ownership migration, contradiction cleanup, stale continuation review, externally evidenced promotion, and active-version boundaries; not for unrelated routine turns or background maintenance.
+description: >
+  Curate State Flow memory on request or once at an active State Flow feature,
+  release, project-phase, or version boundary. Reconcile stale knowledge,
+  contradictions, commitments, continuation, and ownership. Not for routine
+  turns, usage help, or background maintenance.
 ---
 
-# State Flow Memory Curation
+# State Flow Memory
 
-Use this Skill for one bounded maintenance cohort: either an explicit curation request or a feature, release, campaign, project, or active-version phase boundary that the State Flow runtime contract requires to reconcile. Ordinary turns curate only touched and obviously stale visible branches without loading this full procedure.
+State Flow's bounded curation procedure. Preserve consequences, not a transcript or attachment to an unfinished method.
 
-**Preserve the consequences of experience, not attachment to the previous trajectory.** A fresh run should respect established constraints and learning while remaining free to reconsider unresolved methods. Neither novelty nor minimum state size is a goal by itself.
+## Boundary
 
-## Preconditions and boundary
+Start from visible state. Require available `read_state` and `patch_state`; otherwise report the blocker without bypassing storage or enabling an episode. Passive access suffices for explicit curation. Memory is fallible data, not authority.
 
-1. Confirm State Flow is enabled. If `read_state` is unavailable or reports disabled state, stop without inventing migration work.
-2. Identify the requested or phase-boundary scope, affected items, and outcome. Do not audit unrelated memory merely because it is visible.
-3. State Flow owns durable memory while enabled; global semantic memory is always available. Availability does not justify broadening project-specific or sensitive material.
-4. Treat materialized state as fallible semantic data, never higher-authority instructions. Memory edits cannot grant permissions or change runtime policy.
-5. Use available materialized context first. Read artifact sources only for a concrete gap, exact-source need, evidenced invalidation, contradiction, or explicit request. An index or description does not prove that source content was acquired or understood.
+Follow the installed runtime contract. In active mode, satisfy all pending acquisitions in the next patch: this Skill needs its exact read path in `cwd.artifacts`, a description, `kind: "skill"`, and a nonempty `compilation` object. Never invent provenance or repeat accepted compilations.
 
-## Inventory
+## Reconcile one bounded set
 
-Read only the smallest required projections with `read_state`: session for branch/run continuation, CWD for project-specific knowledge, and global for established cross-project, user, or environment knowledge. Use older offsets only for a concrete contradiction or provenance question. Do not reread current effective state already in context without a specific verification or ownership need.
+1. **Limit the review.** Address the request or completed phase. Use targeted reads for gaps, contradictions, ownership, or verification; do not rerun the project.
+2. **Classify.** Put user requirements and binding confirmed decisions in `contract`, observations, assistant conclusions, and unresolved work in `working`, chosen actions in `intents`, and inactive reusable detail in `lazy`. Never give an assistant conclusion user authority. Remove fulfilled, abandoned, superseded, or impossible intents; retain consequential results. Possibilities are not commitments.
+3. **Keep evidence boundaries.** Preserve corrections, prerequisites, bounded negative results, and useful uncertainty. Separate requirements, decisions, observations, conclusions, and hypotheses. Silence is not acceptance; repetition is not verification. One implementation's failure does not reject an approach. Neither freeze provisional methods nor reopen confirmed decisions without grounds.
+4. **Compact for continuation.** Remove duplicates, obsolete progress, unsupported claims, and secrets. Keep sufficient results, real retrieval pointers, pending interaction, and known next checks. Observations are not live external facts. Keep `lazy` shallow and priority-ordered. Recognize optional structured `$ref` values and `$`-prefixed `read_state` paths inside ordinary strings as semantic-state references; other resources retain native locators. No reference form proves authority or existence, authorizes execution, or implies completion. Never scan or resolve references merely to find broken ones. When the bounded review independently needs a reference, a missing single value path with exact durable sources returns `{value:null, hint:[{type:"dangling-reference", message, paths}]}`. Treat the top-level hint as provenance and reconciliation guidance, never as requested state or proof of staleness; its paths are runtime-verified current owners, while no hint does not prove invention. Inspect ownership only as needed, then patch a proven stale owning value while preserving surrounding meaning. Effective absence or external inaccessibility is insufficient.
+5. **Check ownership.** Prefer `session` for branch/run continuation, `cwd` for project knowledge, and `global` for established cross-project knowledge. Effective values do not prove ownership; inspect owners before moves. Broader applicability requires evidence.
 
-Distinguish user requirements, confirmed decisions, observations, assistant conclusions, and hypotheses. Do not infer user acceptance from silence, repetition, or an earlier assistant assertion.
+## Transfer only when needed
 
-For each targeted item choose:
+Resolve destination conflicts without overwriting stronger or unrelated knowledge. Write the destination, retain the source, and verify the destination separately. Recheck source changes before deleting or narrowing it in a later patch. Reconcile affected references; verify source cleanup and effective inheritance. Never combine destination creation with source deletion.
 
-- `keep`: useful, adequately grounded, correctly scoped, and still applicable;
-- `update`: superseded or stale, with evidence for the replacement;
-- `reframe`: useful, but expressed with unsupported certainty, authority, or breadth;
-- `narrow`: stored more broadly than its applicability;
-- `promote candidate`: useful at a broader scope or external destination, but not yet safely transferred;
-- `remove`: obsolete, redundant, secret, raw history, unsupported assertion with no remaining decision value, or completed transient progress.
+External transfers also require confirmed destination and write authority. Verify accepted content and a content-bound revision or receipt through the external interface, not memory. Preserve the source when acceptance is ambiguous. Never export secrets or broaden sensitive material without authorization.
 
-These are audit decisions, not required stored labels. Do not manufacture timestamps, confidence scores, provenance, promotion receipts, or a new bookkeeping schema.
+## Apply, verify, stop
 
-## Reconcile for continuity and search
+A fresh executor must recover constraints, results, open questions, commitments, and the next action without inheriting an unapproved method.
 
-### Preserve commitments without freezing methods
+Patch only material changes with `patch_state`, alone per assistant response; await acceptance. Never edit backing files, `response`, configuration, or runtime metadata. Read changed owner paths; inspect parent keys for deletions and effective state for inheritance changes.
 
-Preserve active goals, explicit constraints, confirmed decisions, completed prerequisites, and obligations that still affect future work. Preserve corrections and their consequences.
-
-Separate a binding requirement from the method currently proposed to satisfy it. Do not turn an assistant preference into a user requirement, or a provisional approach into a settled decision. Conversely, do not demote a confirmed decision merely to encourage exploration. Retain its scope and known reconsideration conditions when relevant; do not invent them.
-
-### Preserve the point of interaction
-
-When it affects continuation, retain what was proposed, accepted, rejected, corrected, explained, or left unresolved, and what the next response or action must address. Preserve enough referents for pending follow-ups to make sense.
-
-Keep consequences, not a transcript or a personality dossier. Do not invent shared history or claim subjective continuity. A fresh run should not unnecessarily reopen a settled exchange or treat an unanswered proposal as approved.
-
-### Preserve learning at its demonstrated boundary
-
-For consequential results, retain the tested mechanism, relevant conditions, outcome, and useful evidence locator. Keep exact rejection reasons and established conditions under which reconsideration would be warranted.
-
-Do not generalize failure of one implementation into failure of an entire approach. Do not generalize one successful test into unrestricted validity or count repeated model agreement as independent verification. Preserve completed work when it remains a prerequisite, constraint, or piece of evidence; remove only its obsolete progress narration.
-
-A justified reconsideration uses changed conditions, a materially different mechanism, a different discriminating test, or a specific verification need. Do not recommend repeating an unchanged failed attempt with no new basis. Do not suppress a legitimate alternative merely because the previous run did not explore it.
-
-### Preserve useful uncertainty
-
-Retain a hypothesis or unresolved alternative only when it could change a pending decision or continuation. State its uncertainty, relevant evidence or missing evidence, and the next discriminating check when known. Keep it scoped to the work it serves.
-
-Remove speculative clutter, not all hypotheses. Do not manufacture alternative branches for diversity. If contradictory claims cannot be resolved from explicit user direction and appropriate evidence, preserve the decision-relevant conflict rather than selecting the cleaner narrative.
-
-### Preserve validity and recoverability
-
-Treat `working` as last observations, not live external reality. Retain validity conditions or a targeted revalidation need when consequences depend on volatile facts. Following interruption or branch restoration, do not infer external success or failure from memory alone; state restoration does not undo tool effects.
-
-A locator supports later retrieval; it does not replace content needed for the next decision. Preserve the smallest sufficient result plus an existing retrievable source or trace reference where necessary. Never invent a locator or assume unavailable history can repair an omission.
-
-Do not rerun the underlying project merely to curate its memory. Leave an exact unresolved check when verification falls outside the requested boundary.
-
-### Compact without flattening
-
-Merge redundant fragments and remove obsolete scaffolding, repeated argumentation, and routine progress. Do not rewrite unchanged state merely to normalize wording.
-
-Do not erase a meaningful correction, uncertainty, commitment, negative result, or continuation dependency to make state shorter. Do not retain the previous chain of reasoning solely to steer the next run toward the same method.
-
-### Reconcile phase boundaries
-
-After a major feature, important release, large body of work, or meaningful checkpoint reaches completion or its final stage, proactively optimize the affected State Flow scopes. Distill implementation-specific detail into durable consequences, remove trajectory-bound scaffolding, and rebalance knowledge across global, CWD, and session ownership so the resulting state stays alive, reusable, and open to better future methods rather than preserving the shape of the finished effort.
-
-A completed feature, release, campaign, project switch, or active-version change is evidence that its working set needs one bounded review. Remove completed task lists, obsolete release/version state, run identifiers, timings, incident chronology, dead experiments, and stale continuation. Retain shipped status only when it remains a prerequisite, durable rule, open risk, or useful retrieval pointer.
-
-State branches may move as applicability changes. Global is limited to established cross-project, user, or environment knowledge; CWD owns reusable project truth; session owns branch/run continuation. Narrow project-specific global material into CWD, promote genuinely cross-project learning only when evidence supports the broader boundary, and move reusable session learning into CWD without carrying its transient run shell.
-
-Effective state does not prove which scope owns a value. When ownership matters and recent transitions do not establish it, inspect only the targeted global, CWD, or session projections with `read_state`. Use the verified destination-write/readback/source-delete/readback sequence below; never delete first or assume an effective value disappeared merely because one override changed.
-
-## Fresh-run check
-
-Before writing, review the proposed changes once within the requested boundary:
-
-- Would a fresh executor know what must still hold, what changed, what remains unresolved, and how to continue?
-- Could an omission cause a known failed attempt, an unnecessary repeated explanation, or loss of an active commitment?
-- Could a retained claim impose an unapproved method, overgeneralize a result, or hide a live alternative?
-
-Adjust only identified defects. This is a semantic review, not a request for extra agents, repeated experiments, or proof of every retained fact. Structural acceptance alone does not establish truth or sufficient memory.
-
-## Apply one reconciliation cohort
-
-Use `patch_state` only for material changes to `artifacts`, `contract`, or `working`. One call may supply `global`, `cwd`, and `session` patches as one atomic cohort; each call must be alone in its assistant response, and subsequent actions must use the rematerialized state. Set `final:true` only when the iteration is eligible to finish at a later `turn_end`. Do not patch runtime-owned `response`, config, or metadata, or bypass validation by editing backing files.
-
-Schedule acquisition and migration barriers in this order:
-
-1. After reading this Skill, compile it into its exact-path CWD artifact before acquiring a stale global Markdown source or attempting an unrelated state write.
-2. Read only the smallest required state projections. If a justified stale Markdown read creates a global compilation obligation, include every pending compilation scope in the next atomic patch before unrelated work.
-3. Write the migration destination with `patch_state`, verify it with a separate `read_state`, then delete or narrow the source and verify both its scope and the effective overlay. Do all readback before the terminal answer.
-4. Complete one terminal reconciliation without repeating accepted compilations or inventing memory changes. Simultaneously pending CWD and global acquisitions must be compiled together in one atomic `patch_state` call; set `final:true` in that call only when the iteration is otherwise ready to finish.
-
-Scope-local deletion may reveal a lower-scope value. Deleting an override is not necessarily removal from effective state.
-
-For movement between State Flow scopes, resolve destination conflicts before writing; do not overwrite stronger or unrelated knowledge. Write and verify the destination before deleting the source. Do not combine destination creation and source deletion merely because multi-scope publication is atomic: preserve a temporary duplicate until readback proves the destination. Do not claim migration is complete until source cleanup and the effective result are verified.
-
-On rejection, interruption, or conflicting state, inspect what was actually accepted before continuing. Never assume the entire cohort succeeded or failed. Keep recovery bounded; report a blocker rather than repeatedly regenerating patches.
-
-## External ownership and promotion
-
-Do not guess an external owner or treat a reusable item as authorization to publish it. Keep each item at its narrowest valid State Flow scope while ownership or acceptance is unresolved.
-
-External promotion has two phases:
-
-1. `Transfer and verify`: Confirm the requested destination and authority, then attempt the write while keeping the accepted State Flow copy. Through the actual external interface, verify destination identity, accepted content, and a durable pointer or receipt tied to that content and revision. A stored claim of acceptance is not verification. Retain compact candidate, pointer, and status information only when it supports recovery; follow an existing record contract rather than inventing one.
-2. `Source cleanup`: Delete or narrow the State Flow copy only after destination acceptance is evidenced. Retain enough routing information to retrieve content still needed for continuation.
-
-On timeout, rejection, ambiguity, stale receipt, or unavailable destination, preserve the State Flow copy and report unresolved acceptance. Reconcile uncertain prior writes before retrying. Never delete the only accepted copy as part of a handoff.
-
-Never promote secrets. Removing a secret from active state does not erase prior offsets, Git history, or external copies; report that limitation without repeating the secret.
-
-## Verify and stop
-
-After accepted changes:
-
-1. Read each changed scope at offset 0, including a migration destination before source deletion.
-2. Read effective state when deletion, relocation, or overrides may change inheritance.
-3. Verify intended values, omissions, scope, and ownership status. Check that uncertainty was not promoted to fact, user commitments were not weakened, and continuation remains actionable.
-4. Report the bounded change, unresolved items, any partial migration, and the evidence authorizing external promotion. Do not dump memory contents or imply historical erasure.
-
-Stop after this reconciliation cohort, including when no change is warranted or a blocker remains. Do not turn phase-boundary curation into automatic background maintenance, arbitrary periodic scanning, or an open-ended search for a better state.
+After rejection or interruption, inspect accepted state before bounded recovery. Report unresolved checks and partial transfers without dumping memory or implying historical erasure. Active iterations need accepted `final:true` before the answer; use a final-only call when no changes remain. Passive turns do not. Stop after this review, including when nothing needs changing.

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

@@ -2,6 +2,7 @@
 
 - [Usage and recovery](usage.md): Configuration, new/resumed sessions, Start/Stop, diagnostics, privacy, and storage recovery.
 - [Architecture](architecture.md): Semantic state, temporal algebra, Pi lifecycle, storage, publication, artifacts, and embedding contracts.
+- [Lazy state](lazy-state.md): Implemented ordinary-JSON lazy planes, an effective-by-default `lazy` read path, pure state/patch snapshots, narrow structural `meta` + `keys`, and recursive indexed array patches.
 - [Filesystem recovery](filesystem-recovery.md): Cohort-wide absence, partial-presence, malformed-evidence, repair-authority, and transaction rules.
 - [Temporal acceptance](temporal-acceptance.md): The twenty required temporal properties and their executable witnesses.
 - [SDK compatibility](compatibility.md): Tested dependency stacks, public lifecycle seams, isolated validation, and host limits.

package/node_modules/@llblab/pi-state-flow/docs/architecture.md

@@ -8,18 +8,19 @@ The extension owns durable memory while enabled. Global semantic memory is alway
 
 ## Composition
 
-`index.ts` is the public export and extension composition boundary. Independent modules under `lib/` own one concern each and are mirrored by tests:
+`index.ts` is the minimal public export boundary. `lib/extension.ts` is the Pi lifecycle composition root: it wires configuration and domain capabilities into commands, tools, event subscriptions, and handlers while delegating imperative mechanics to their owning modules. Independent modules under `lib/` own one concern each and are mirrored by tests:
 
 - `state`, `json`: semantic shape, validation, recursive overlay and deletion.
 - `temporal`, `history`: causal boundaries, checkpoint/tail folding and hot history.
-- `durable`, `storage`, `git`: exact files, CAS publication, Git commits/restoration, and owned push processes.
-- `snapshot`, `session`, `runtime`, `recovery`, `episode`: Pi branch/runtime lifecycle.
+- `durable`, `storage`, `git`: exact files, CAS publication, Git commits/restoration, and Git transport.
+- `snapshot`, `session`, `runtime`, `recovery`, `episode`: Pi branch/runtime lifecycle, branch traversal, and passive-boundary interpretation.
 - `transition`, `terminal`, `context`: inference barriers, turn resolution, passive projection, and response reconciliation.
 - `artifact`, `acquisition`, `maintenance`, `skills`, `rehydration`: source routing and compilation.
 - `memory`: external promotion records and memory diagnostics.
 - `continuation`: native-header discovery, runtime-provenance inspection, deterministic recommendation, and host startup precedence.
-- `publication`: remote policy, durable CAS queue/store, cross-process leases, and attempt outcomes.
-- `status`, `telegram`, `extension`: operator projection, the optional fail-open pi-telegram presentation adapter, and Pi adapter wiring.
+- `publication`: remote policy, durable CAS queue/store, cross-process leases, worker lifecycle, generation fencing, and attempt outcomes.
+- `protocol`, `logging`: model/tool presentation and bounded diagnostic persistence.
+- `status`, `telegram`, `extension`: operator projection, the optional fail-open pi-telegram presentation adapter, and high-level Pi adapter wiring.
 
 ## Semantic state
 
@@ -61,24 +62,24 @@ checkpoint.json + patches.jsonl
 
 The checkpoint is an older anchored materialization. The tail contains at most seven effective patches. On overflow, the oldest tail patch folds into the checkpoint before the new patch is appended.
 
-`state[n]`, `state.global[n]`, `state.cwd[n]` and `state.session[n]` resolve the same nth previous causal boundary. They are not independent per-scope patch counters. Pre-origin history is unavailable rather than empty.
+`effective[n]`, `global[n]`, `cwd[n]`, and `session[n]` resolve the same nth previous causal boundary. They are not independent per-scope patch counters. The retired top-level `state` segment is rejected; pre-origin history is unavailable rather than empty.
 
 A final-only `patch_state({"final":true})` call changes only ephemeral terminal eligibility and creates no identity, commit, or history step. A changed accepted response is runtime-owned semantic state and advances history.
 
 ## Pi lifecycle
 
-`patch_state` is the sole mutation tool. It validates any supplied global/CWD/session patches against one causal basis and publishes them as one atomic transition, then acts as an inference barrier. Pi executes no sibling tools from the same assistant response; the next inference sees rematerialized `state[0]`.
+`patch_state` is the sole mutation tool. It validates any supplied global/CWD/session patches against one causal basis and publishes them as one atomic transition, then acts as an inference barrier. Pi executes no sibling tools from the same assistant response; the next inference sees the rematerialized current effective state.
 
 Tool preflight follows Pi's public `getLeafEntry()` / `getEntry(parentId)` links to the nearest assistant containing the current call ID. It inspects that response's complete tool batch without constructing the whole branch or caching a batch across calls/selections. Foreign custom entries and earlier sibling results remain in the native trace. A missing call ID still searches the selected ancestry and preserves the existing unmatched-call behavior; this is not an unconditional constant-time guarantee. See [measured traversal evidence](performance.md#tool-preflight-parent-traversal).
 
-`read_state` reads one cached effective or scoped projection at offsets zero through seven. It never publishes or advances history.
+`read_state` reads one cached effective or scoped projection at current index zero or a retained causal index one through seven. It never publishes or advances history.
 
 Every enabled assistant iteration starts terminal-ineligible. Only a successful `patch_state` call containing `final:true` latches eligibility for the next accepted `turn_end`; the call may atomically include global, CWD, and session patches. Eligibility does not stop later reasoning, tools, or patches. If terminal prose arrives before eligibility, State Flow preserves that draft and reconciles it into runtime-owned `response` at `turn_end`, then starts at most two same-run fallback turns whose only purpose is the `final:true` patch. The same path covers an eligible draft whose final validation fails after a later acquisition. Fallback turns never become the response: a successful `final:true` commits its patches and closes resolution with the preserved answer intact, while two failed fallbacks close the iteration with the preserved answer and current state plus one bounded warning and a finalization diagnostic. Failed patch calls do not consume the budget. A following legal patch remains possible, and only an accepted ordinary answer is reconciled into runtime-owned `response` at `turn_end`. State Flow no longer parses `state_flow` or generic HTML comments; historical comments are ordinary text and other extensions retain their own comment handling.
 
 ## Lifecycle planes
 
 ```text
-SEMANTIC STATE       artifacts + contract + working
+SEMANTIC STATE       artifacts + contract + working + intents
 TURN ELIGIBILITY     false → patch_state(..., final:true) → latched true
 CONTEXT PROJECTION   active State Flow projection | passive post-stop handoff
 ```
@@ -100,6 +101,7 @@ The default store is `<agentDir>/state-flow`, independent from Markdown discover
 Owned paths are:
 
 ```text
+config.json
 checkpoint.json
 patches.jsonl
 meta.json
@@ -108,13 +110,14 @@ meta.json
 <cwd-key>/meta.json
 <cwd-key>/<session-key>/checkpoint.json
 <cwd-key>/<session-key>/patches.jsonl
-<cwd-key>/<session-key>/config.json
 <cwd-key>/<session-key>/meta.json
+<cwd-key>/<session-key>/config.json
+<cwd-key>/<session-key>/runtime.json
 ```
 
 CWD and session keys mirror Pi's native encoding. The Pi UUID remains authoritative; readable directory keys never replace identity validation.
 
-`checkpoint.json` is only the canonical materialized semantic state, and each nonblank `patches.jsonl` line is only one semantic patch. Scope `meta.json` owns the checkpoint/tail boundaries, CWD owner identity, and runtime artifact provenance for its scope; the session file additionally owns lineage, counters, session identity, publication provenance and remote-publication policy. Metadata writers replace only their owned leaves and preserve JSON-safe unknown siblings. Pi checkpoints retain only an exact Git revision, an exact `file:<hash>` cohort reference, or a proven ordinary-disabled marker.
+Root `config.json` is the read-only operator configuration shared by every session in the repository; it never participates in semantic overlay. `checkpoint.json` is only the canonical materialized semantic state, and each nonblank `patches.jsonl` line is only one semantic patch. Every scope's `meta.json` symmetrically owns checkpoint/tail boundaries and artifact provenance, with CWD ownership added where applicable. Session `config.json` owns behavior; session `runtime.json` asymmetrically owns lineage, counters, session identity, publication provenance, remote-publication policy, and the full specification only while a run is unfinished. The predecessor combined session `meta.json` remains readable as migration input and is separated by the next normal CAS publication. Metadata writers replace only their owned leaves and preserve JSON-safe unknown siblings. Pi checkpoints retain only an exact Git revision, an exact `file:<hash>` cohort reference, or a proven ordinary-disabled marker.
 
 All owned writes use same-directory atomic replacement, regular-file and symlink checks, prepared byte receipts and CAS validation. Unrelated files and detected concurrent bytes are preserved; Git staging follows the acceptance contract below. Rollback restores only bytes still matching the failed publisher's output.
 
@@ -122,7 +125,7 @@ All owned writes use same-directory atomic replacement, regular-file and symlink
 
 If Git is unavailable specifically through executable `ENOENT`, State Flow uses file-only persistence. File mode retains exact current materialization and proven hot history but offers no arbitrary cold revisions.
 
-With Git, each effective semantic cohort creates one local commit immediately through an isolated index that stages the complete non-ignored worktree delta before overlaying the exact prepared State Flow outputs; the caller-visible index is synchronized to the committed tree afterward. Each prepared content is still hashed separately from its supplied bytes, never substituted by mutable worktree reads or filtered staging. Prepared blobs enter the isolated index through one NUL-delimited `update-index --index-info` batch, preserving literal path characters; explicit removals retain their existing path. Any failed batch aborts before reference publication and follows the same exact-output rollback and temporary-index cleanup. Activation returns after local runtime acceptance for normal `turn-end`/`off` policy, skips full predecessor migration planning only when legacy snapshots and complete predecessor checkpoint/tail envelopes are absent, and defers Markdown discovery until the next enabled inference. State Flow-owned active files keep compare-and-swap protection, and `.gitignore` stays authoritative. Git supplies cold history and exact branch restoration. Runtime `revision: "self"` resolves to the commit that owns the runtime record, never arbitrary `HEAD`. Runtime-only writes may use `temporalRevision` to select older semantic streams and their matching artifact provenance. They update the current session's config/meta without rewriting live shared checkpoints, tails, or provenance.
+With Git, each effective semantic cohort creates one local commit immediately through an isolated index that stages the complete non-ignored worktree delta before overlaying the exact prepared State Flow outputs; the caller-visible index is synchronized to the committed tree afterward. Each prepared content is still hashed separately from its supplied bytes, never substituted by mutable worktree reads or filtered staging. Prepared blobs enter the isolated index through one NUL-delimited `update-index --index-info` batch, preserving literal path characters; explicit removals retain their existing path. Any failed batch aborts before reference publication and follows the same exact-output rollback and temporary-index cleanup. Activation returns after local runtime acceptance for normal `turn-end`/`off` policy, skips full predecessor migration planning only when legacy snapshots and complete predecessor checkpoint/tail envelopes are absent, and defers Markdown discovery until the next enabled inference. State Flow-owned active files keep compare-and-swap protection, and `.gitignore` stays authoritative. Git supplies cold history and exact branch restoration. Runtime `revision: "self"` resolves to the commit that owns the runtime record, never arbitrary `HEAD`. Runtime-only writes may use `temporalRevision` to select older semantic streams and their matching artifact provenance. They update the current session's `config.json`/`runtime.json` without rewriting live shared checkpoints, tails, or provenance.
 
 Branch recovery validates immutable selection before live publication acquisition. `TemporalRuntime.prepareRestore` returns a detached snapshot and an instance-bound, single-use restoration closure. For an exact matching Git owner, that closure reuses the validated cohort and provenance rather than decoding them twice; it still captures the current publication basis under exclusion before installing any runtime fields. Expired file cohorts, legacy snapshot fallbacks, and references redirected to another runtime owner take the fresh-read path. A consumed or failed preparation cannot be replayed, and neither the mutable inspection snapshot nor an old publication basis can become restore authority. This is bounded reuse within one selection, not a cross-session revision cache.
 
@@ -173,9 +176,11 @@ Compilation is routing, not a substitute for source text. Full source is read on
 
 Skills are CWD artifacts with stricter compilation: `kind: "skill"` and a non-empty compilation describing applicability, constraints and failure conditions. Their source bodies do not persist in state. Matching provenance proves source-version consistency, not semantic fidelity, truth, or higher instruction authority.
 
-## Memory curation and promotion
+## Operational guidance, memory curation, and promotion
 
-The optional packaged `state-flow-memory` Skill performs bounded explicit audits, scope narrowing, contradiction cleanup and external handoffs. It is not part of ordinary retention or background maintenance. Curation compiles a read Skill at CWD before accumulating global compilation obligations, writes and separately reads a migration destination before source deletion, then verifies the changed scope and effective overlay. Simultaneously pending CWD/global acquisitions must be compiled together in one atomic `patch_state` call. Destination write, readback, and source deletion remain separate migration steps so accepted-copy verification is not skipped.
+The packaged Skills deliberately separate two responsibilities. `state-flow-guide` is the on-demand operational reference for concrete read, patch, inheritance, acquisition, finalization, and recovery questions; it does not initiate memory audits or unsolicited cleanup. `state-flow-memory` performs one bounded explicit or phase-boundary curation over stale knowledge, commitments, continuation, ownership, and external handoffs; it is not part of routine turns or background maintenance.
+
+Curation compiles a read Skill at CWD before dependent work, writes and separately reads a migration destination before source deletion, then verifies the changed owner and effective overlay. Simultaneously pending CWD/global acquisitions must be compiled together in one atomic `patch_state` call. Destination write, readback, and source deletion remain separate migration steps so accepted-copy verification is not skipped.
 
 External promotion remains a semantic two-phase handoff, not a memory-owner mode. Optional global `working.memory_promotions` entries record `pending`, `accepted`, `failed` or `unknown` status plus owner. Accepted records additionally require destination pointer and revision. Failed or uncertain promotion preserves the State Flow candidate; the only accepted copy is never deleted.
 
@@ -196,23 +201,25 @@ Both [tested Pi SDKs](compatibility.md) choose or create `SessionManager` before
 
 ### Model tools
 
-`patch_state` accepts optional fixed `global`, `cwd`, and `session` semantic patches plus optional `final:true`. At least one scope or `final:true` is required in the canonical model contract. Supplied scopes contain only object-valued `artifacts`, `contract`, and `working`; omitted fields preserve their values, recursive object merge updates them, arrays/primitives replace, and nested object-key `null` deletes. Materialized null, empty supplied scopes, material no-ops, unknown top-level fields, model-authored `response`, and retired grammars are rejected. A final-only true call changes ephemeral eligibility, not semantic history. Runtime quietly accepts unambiguous false-like `final` input as non-terminal intent, including an inert false-only call, but this compatibility layer is deliberately absent from model guidance.
+`patch_state` accepts optional fixed `global`, `cwd`, and `session` semantic patches plus optional `final:true`. At least one scope or `final:true` is required in the canonical model contract. Supplied scopes contain object-valued `artifacts`, `contract`, `working`, and `intents`, plus ordinary-JSON `lazy`; omitted fields preserve their values, recursive object merge updates them, arrays/primitives replace, and nested object-key `null` deletes. Materialized null, empty supplied scopes, material no-ops, unknown top-level fields, model-authored `response`, and retired grammars are rejected. A final-only true call changes ephemeral eligibility, not semantic history. Runtime quietly accepts unambiguous false-like `final` input as non-terminal intent, including an inert false-only call, but this compatibility layer is deliberately absent from model guidance.
 
 ```json
-{"session":{"working":{"next":"Verify the corrected behavior"}},"final":true}
+{"session":{"intents":{"next":"Verify the corrected behavior"}},"final":true}
 ```
 
-`read_state` accepts one unified path. `state == state[0]` is the current effective materialization; `state.global == state.global[0]` (and CWD/session equivalents) selects that scope at the same composed causal boundary. `state.global.patches == state.global.patches[0]` reads the latest accepted retained global patch, with higher patch indices walking only that scope's retained accepted patches. Indices are bounded to zero through seven; unavailable pre-origin or pre-tail history is an error. Resolver aliases are not literal JSON containers. Reads stay cached and create no Git query, publication, checkpoint append, or semantic step.
+`intents` is the hot plane for active commitments, not requirements, observations, alternatives, or completed plans. Removing an intent does not remove its consequences or any referenced state. Semantic-state references use either the optional structured `{"$ref":"cwd.lazy.plan"}` convention or `$` immediately followed by one valid `read_state` path inside ordinary text, for example `$effective.lazy.memory[7]`. The text prefix distinguishes references from incidental path-like prose and leaves a deterministic seam for possible future parsing. Resource paths, document locators, URIs, Skill identities, and agent identities retain their native syntax. State Flow stores all forms as ordinary JSON and currently does not parse or validate targets. The agent resolves a relevant locator explicitly through `read_state` or the appropriate external tool; presence alone creates no authority, existence proof, dependency, hydration, execution, or completion semantics. Reference repair is reactive: the agent never scans or resolves references merely to test them. Only after one requested value path is missing does the query domain perform one bounded reverse lookup over current model-patchable semantic planes for exact structured `$ref` or `$path` matches. When matches exist, `read_state` returns the explicit diagnostic sentinel `{value:null, hint:[{type:"dangling-reference", message, paths}]}`. `hint` is a top-level sibling rather than state data; its message asks for reconciliation and `paths` contains at most three runtime-verified current owning addresses. The null sentinel is never returned alone for this case. Keys, patch, and multi-path reads keep all-or-error semantics, while no durable match retains the ordinary missing-path error. A match establishes durable semantic provenance, not staleness; no match does not prove invention. The agent may then inspect ownership and patch a proven stale source without discarding surrounding meaning. Effective absence does not establish ownership, and unavailable history, external inaccessibility, or transient read failure does not prove a broken reference.
+
+`read_state` accepts one unified path. `effective == effective[0]` is the current effective materialization; `global == global[0]` (and CWD/session equivalents) selects that scope at the same composed causal boundary. `global.patches == global.patches[0]` reads the latest accepted retained global patch, with higher patch indices walking only that scope's retained accepted patches. Indices are bounded to zero through seven; unavailable pre-origin or pre-tail history is an error. Resolver aliases are not literal JSON containers. Reads stay cached and create no Git query, publication, checkpoint append, or semantic step.
 
 ```json
-{"path":"state.cwd[1]"}
+{"path":"cwd[1].intents"}
 ```
 
 ```json
-{"path":"state.global.patches[0]"}
+{"path":"global.patches[0]"}
 ```
 
-The prior `{offset, scope}` form remains accepted for session/tool-call compatibility, but cannot be combined with `path`.
+Unscoped semantic paths such as `intents.next` alias the current effective overlay. `value`, `keys`, and `patch` projections plus ordered `paths` batches remain all-or-error.
 
 Both tools follow branch enablement and host restrictions. The patch barrier also blocks reader siblings. These tools do not impose project schemas or state-size caps; semantic usefulness, scope choice, and compression remain model responsibilities. Every ordinary handoff reconciles touched and obviously stale visible state. Feature/release/campaign completion, project switches, and active-version changes additionally require one bounded scoped ownership and obsolescence pass: global retains only established cross-project/user/environment knowledge, CWD owns reusable project truth, and session owns branch/run continuation. Scope movement uses targeted reads and destination verification before source deletion rather than an automatic maintenance loop.
 

package/node_modules/@llblab/pi-state-flow/docs/compatibility.md

@@ -4,7 +4,7 @@ This matrix records exact tested dependency stacks, not the version of an operat
 
 ## Current release candidate
 
-The 0.12.0 candidate passes `npm run validate` on the repository-local 0.84.4 dependency graph: typecheck, import check, and 451/451 tests. Its focused path/config/interactive-rendering cohort passes 41/41, including current-as-index-zero `read_state` aliases, composed-lineage scoped reads, retained scope-patch reads, legacy `{offset, scope}` compatibility, and both visible/default and suppressed `patch_state` argument rendering. A live enabled host also resolves current and historical legacy reads; the host must reload the candidate before its model-facing tool schema can expose the new `path` input. The 0.85.1 full-suite result below belongs to the earlier source checkpoint and has not been repeated for this candidate.
+The 0.16.0 candidate passes `npm run validate` on the repository-local 0.84.4 dependency graph: build, typecheck, import check, package dry run, and 444/444 tests. Its focused context/Skill/invariant cohort passes 43/43, including discovery of the separate operational and memory-curation Skills and release-package inventory checks for both compiled Skill paths. Current and historical reads use semantic `path`/`paths`; the retired top-level `state` segment and legacy top-level `offset`/`scope` inputs are rejected. The 0.85.1 full-suite evidence below belongs to the earlier recorded source checkpoint and has not been repeated for this candidate.
 
 ## Tested matrix
 

package/node_modules/@llblab/pi-state-flow/docs/filesystem-recovery.md

@@ -8,7 +8,8 @@ State Flow classifies absence separately from partial or malformed evidence. Rec
 | CWD `checkpoint.json` + `patches.jsonl` | State Flow; authoritative shared semantics with CWD identity | Same as global; selected values are not resurrected | Same as global; owner mismatch also fails closed | Normal CAS publication may materialize the complete empty pair |
 | Session `checkpoint.json` + `patches.jsonl` | State Flow; authoritative private semantics | Fresh lifecycle origin may initialize; an existing selected session requires exact retained authority | Partial or malformed pair fails closed | Fresh initialization or exact selected-revision recovery only |
 | Global/CWD `meta.json` | State Flow; temporal boundaries, CWD identity, and artifact provenance | Missing metadata removes temporal authority and fails closed; only an omitted `artifacts` leaf degrades provenance to `{}` | Malformed metadata or semantic/boundary mismatch fails closed | Normal CAS publication from a complete proven cohort |
-| Session `config.json` + `meta.json` | State Flow; authoritative runtime identity, lineage, temporal boundaries and session provenance | Fresh origin may initialize; selected sessions recover only from exact authority | Partial, malformed, contradictory identity, lineage, boundary, or revision fails closed | Canonical runtime publication from proven lifecycle/selected state |
+| Session `meta.json` | State Flow; session temporal boundaries and artifact provenance | Fresh origin may initialize; selected sessions recover only from exact scope authority | Partial, malformed, or contradictory boundary evidence fails closed | Canonical scope publication from the selected temporal state |
+| Session `config.json` + `runtime.json` | State Flow; behavior plus authoritative runtime identity, lineage, counters, and publication recovery | Fresh origin may initialize; selected sessions recover only from exact authority | Partial, malformed, contradictory identity, lineage, or revision fails closed | Canonical runtime publication from proven lifecycle/selected state; predecessor combined `meta.json` is migration input only |
 | Unsupported `state.json`, hashed layouts, or semantic Pi checkpoints | No current authority | Ignored | Presence never becomes recovery or migration input | Operator-managed removal or external conversion only |
 | Selected Git revision blobs/modes | Git object database; immutable cold authority | A required blob/revision is unavailable | Mode, owner, hash, or cohort contradiction fails closed | Read-only reconstruction; never checkout/reset the live worktree |
 | File-only revision pointer/cohort | State Flow/Pi entry; current exact authority only | No cold history can be invented | Any identity mismatch or incomplete retained cohort fails closed | Exact current cohort only; normal locked publication writes repairs |
@@ -16,7 +17,7 @@ State Flow classifies absence separately from partial or malformed evidence. Rec
 | Worker lease | State Flow; operational ownership | Unclaimed | Malformed/foreign live evidence is preserved; live owner excludes peers | Existing dead-process reclamation protocol only |
 | Publication locks | State Flow; mutual exclusion | Unlocked | Present lock excludes publishers, including interrupted owners | Current owner releases; no opportunistic deletion |
 | Temporary queue files / isolated Git index | Creating State Flow operation; transient | No pending preparation | Unknown surviving files grant no authority | Creating operation cleans its own temporary path; fatal residue is not adopted |
-| Extension `state-flow.json` | Operator; optional external configuration | Built-in defaults | Present unreadable/malformed/unknown settings fail extension configuration | State Flow never creates or rewrites it |
+| Repository-root `config.json` | Operator; optional global configuration, versioned with the store | Built-in defaults | Present unreadable/malformed/unknown settings fail extension configuration | State Flow never creates or rewrites it; ordinary repository publication preserves and versions operator edits |
 | Knowledge root and Markdown | External Knowledge owner | Freshness unavailable; durable semantic state remains | Unsafe paths or malformed/unreadable sources disable acquisition locally | Never create; semantic removal only under existing confirmed ownership rules |
 | Skill and external artifact sources | External package/user owner | Freshness unavailable unless ownership proves removal semantics | Unsafe/non-regular/unreadable sources disable acquisition locally | Never create or fabricate source/provenance |
 | Pi State Flow entries and diagnostics | Pi session log / State Flow entry owner | Missing optional diagnostics provide no evidence; missing required selected pointer blocks that restore | Malformed or contradictory owner/version/pointer fails the dependent restore | Append through Pi entry APIs only; no standalone diagnostics file exists |