@llblab/pi-kit 0.15.0 → 0.17.0

package/node_modules/@llblab/pi-state-flow/dist/lib/snapshot.js

@@ -42,7 +42,7 @@ export function validateSessionRuntime(value, cwd, sessionId) {
         throw new Error("Invalid State Flow runtime configuration or counters");
     }
 }
-export function createSessionRuntime(snapshot, cwd, sessionId, lineage, publication = "unconfirmed", artifacts = {}) {
+export function createSessionRuntime(snapshot, cwd, sessionId, lineage, publication = "unconfirmed", _artifacts = {}) {
     const { durableBase: _base, pendingPublication: _publication, ...fields } = snapshot.meta;
     const runtime = {
         config: structuredClone(snapshot.config),
@@ -51,7 +51,6 @@ export function createSessionRuntime(snapshot, cwd, sessionId, lineage, publicat
             version: 1,
             identity: { cwd: resolve(cwd), sessionId },
             lineage: structuredClone([...lineage]),
-            ...(Object.keys(artifacts).length === 0 ? {} : { artifacts: structuredClone(artifacts) }),
             revision: "self",
             publication,
         },
@@ -59,51 +58,48 @@ export function createSessionRuntime(snapshot, cwd, sessionId, lineage, publicat
     validateSessionRuntime(runtime, cwd, sessionId);
     return runtime;
 }
-export function serializeSessionRuntime(runtime, cwd, sessionId, stream, existingSource) {
+export function serializeSessionRuntime(runtime, cwd, sessionId) {
     validateSessionRuntime(runtime, cwd, sessionId);
-    let existing = {};
-    if (existingSource !== undefined) {
+    const { temporal: _retiredTemporal, artifacts: _legacyArtifacts, ...runtimeMeta } = runtime.meta;
+    return { config: `${canonicalJson(runtime.config)}\n`, runtime: `${canonicalJson(runtimeMeta)}\n` };
+}
+export function parseSessionRuntime(config, runtimeSource, cwd, sessionId, legacyMetaSource) {
+    let selected = runtimeSource;
+    if (selected === undefined && legacyMetaSource !== undefined) {
+        let legacy;
         try {
-            existing = JSON.parse(existingSource);
+            legacy = JSON.parse(legacyMetaSource);
         }
         catch {
             throw new Error("State Flow session runtime contains invalid JSON");
         }
-        if (!isObject(existing) || !isJsonValue(existing))
-            throw new Error("Invalid State Flow session runtime metadata");
+        if (isObject(legacy) && (Object.hasOwn(legacy, "identity") || Object.hasOwn(legacy, "lineage")))
+            selected = legacyMetaSource;
     }
-    const temporal = stream === undefined ? runtime.meta.temporal : {
-        checkpoint: structuredClone(stream.checkpoint.through),
-        patches: stream.patches.map((record) => structuredClone(record.transition)),
-    };
-    return { config: `${canonicalJson(runtime.config)}\n`, meta: `${canonicalJson({ ...existing, ...runtime.meta, ...(temporal ? { temporal } : {}) })}\n` };
-}
-export function parseSessionRuntime(config, meta, cwd, sessionId) {
-    if (config === undefined && meta === undefined)
+    if (config === undefined && selected === undefined)
         return undefined;
-    if (config === undefined && meta !== undefined) {
+    if (config === undefined && selected !== undefined) {
         let document;
         try {
-            document = JSON.parse(meta);
+            document = JSON.parse(selected);
         }
         catch {
             throw new Error("State Flow session runtime contains invalid JSON");
         }
-        if (isObject(document) && !Object.hasOwn(document, "identity") && !Object.hasOwn(document, "lineage")
-            && Object.keys(document).every((key) => ["version", "artifacts", "temporal", "owner"].includes(key)))
+        if (isObject(document) && !Object.hasOwn(document, "identity") && !Object.hasOwn(document, "lineage"))
             return undefined;
     }
-    if (config === undefined || meta === undefined)
-        throw new Error("Incomplete State Flow config/meta pair");
+    if (config === undefined || selected === undefined)
+        throw new Error("Incomplete State Flow config/runtime pair");
     let runtime;
     try {
-        runtime = { config: JSON.parse(config), meta: JSON.parse(meta) };
+        runtime = { config: JSON.parse(config), meta: JSON.parse(selected) };
     }
     catch {
         throw new Error("State Flow session runtime contains invalid JSON");
     }
     validateSessionRuntime(runtime, cwd, sessionId);
-    const { temporal: _temporal, ...runtimeMeta } = runtime.meta;
+    const { temporal: _legacyTemporal, ...runtimeMeta } = runtime.meta;
     return { config: { enabled: runtime.config.enabled }, meta: runtimeMeta };
 }
 export function resolveSessionRuntime(runtime, revision) {

package/node_modules/@llblab/pi-state-flow/dist/lib/state.d.ts

@@ -1,12 +1,15 @@
 import { type ArtifactCompilationUpdate, type ArtifactRegistry } from "./artifact.ts";
-import { type JsonObject } from "./json.ts";
+import { type JsonObject, type JsonValue } from "./json.ts";
 /** The canonical semantic state shape shared by global, CWD, and session scopes. */
-export interface MaterializedState extends JsonObject {
+export type MaterializedState = JsonObject & {
     artifacts: ArtifactRegistry;
     contract: JsonObject;
     working: JsonObject;
+    intents: JsonObject;
     response: string;
-}
+    /** Absent is the canonical empty lazy plane and preserves predecessor-store compatibility. */
+    lazy?: JsonValue;
+};
 /** Compatibility name for callers that still treat materialized state as a document. */
 export type StateDocument = MaterializedState;
 /** Model patch shape; artifact entries may be compiler outputs before trusted metadata is attached. */
@@ -14,6 +17,7 @@ export interface StatePatch extends JsonObject {
     artifacts: JsonObject;
     contract: JsonObject;
     working: JsonObject;
+    intents: JsonObject;
     response: string;
 }
 export type StateScope = "global" | "cwd" | "session";
@@ -22,6 +26,8 @@ export interface ScopePatch {
     artifacts?: JsonObject;
     contract?: JsonObject;
     working?: JsonObject;
+    intents?: JsonObject;
+    lazy?: JsonValue;
 }
 export interface ScopedPatch {
     scope: StateScope;
@@ -47,6 +53,8 @@ export interface ScopedStates {
 export declare function emptyState(): MaterializedState;
 export declare function isMaterializedState(value: unknown): value is MaterializedState;
 export declare const isStateDocument: typeof isMaterializedState;
+/** Upgrade one exact pre-intents materialized state without inferring commitments. */
+export declare function migratePreIntentState(value: unknown): MaterializedState | undefined;
 /** Atomically replace compiled and removed artifacts inside one materialized scope. */
 export declare function updateMaterializedArtifacts(state: MaterializedState, updates: readonly ArtifactCompilationUpdate[], removed?: readonly string[]): MaterializedState;
 /** Overlay lower-to-higher scopes without mutating any scope document. */

package/node_modules/@llblab/pi-state-flow/dist/lib/state.js

@@ -1,17 +1,26 @@
 import { isArtifactRegistry, projectArtifactsForModel, updateArtifactRegistry, } from "./artifact.js";
-import { applyPatch, isObject } from "./json.js";
+import { applyPatch, isJsonValue, isObject } from "./json.js";
 export function emptyState() {
-    return { artifacts: {}, contract: {}, working: {}, response: "" };
+    return { artifacts: {}, contract: {}, working: {}, intents: {}, response: "" };
 }
 export function isMaterializedState(value) {
     return isObject(value)
         && isArtifactRegistry(value.artifacts)
         && isObject(value.contract)
         && isObject(value.working)
+        && isObject(value.intents)
         && typeof value.response === "string"
-        && Object.keys(value).every((key) => key === "artifacts" || key === "contract" || key === "working" || key === "response");
+        && (!Object.hasOwn(value, "lazy") || (isJsonValue(value.lazy) && value.lazy !== null))
+        && Object.keys(value).every((key) => key === "artifacts" || key === "contract" || key === "working" || key === "intents" || key === "response" || key === "lazy");
 }
 export const isStateDocument = isMaterializedState;
+/** Upgrade one exact pre-intents materialized state without inferring commitments. */
+export function migratePreIntentState(value) {
+    if (!isObject(value) || Object.hasOwn(value, "intents"))
+        return undefined;
+    const candidate = { ...structuredClone(value), intents: {} };
+    return isMaterializedState(candidate) ? candidate : undefined;
+}
 /** Atomically replace compiled and removed artifacts inside one materialized scope. */
 export function updateMaterializedArtifacts(state, updates, removed = []) {
     if (!isMaterializedState(state))
@@ -27,5 +36,6 @@ export function overlayStates(...scopes) {
 }
 /** Model-visible projection: runtime artifact bookkeeping never reaches ordinary context. */
 export function projectStateForModel(state) {
-    return { ...structuredClone(state), artifacts: projectArtifactsForModel(state.artifacts) };
+    const { lazy: _lazy, ...hot } = structuredClone(state);
+    return { ...hot, artifacts: projectArtifactsForModel(state.artifacts) };
 }

package/node_modules/@llblab/pi-state-flow/dist/lib/status.js

@@ -54,7 +54,7 @@ export function detailedStatus(snapshot, diagnostics) {
         `State Flow diagnostics — config.enabled=${snapshot.config.enabled}; branch mode=${snapshot.config.enabled ? "active" : "inactive"}`,
         `Repository: ${diagnostics.repositoryRoot}`,
         `Scope keys: CWD ${diagnostics.cwdScopeKey}; session ${diagnostics.sessionScopeKey}`,
-        "Session files: config.json owns behavior; meta.json owns lineage and provenance",
+        "Session files: config.json owns behavior; runtime.json owns branch recovery; meta.json owns scope provenance",
         `Runtime metadata: step #${snapshot.meta.step}; active revision ${snapshot.meta.durableBase ?? "none"}; bootstrap ${snapshot.meta.bootstrap === true}`,
         `Remote publication policy: ${snapshot.meta.remotePublication?.mode ?? "legacy-transition"}`,
         diagnostics.publicationQueueError !== undefined

package/node_modules/@llblab/pi-state-flow/dist/lib/storage.d.ts

@@ -12,6 +12,8 @@ export declare function detectGitCapability(): "git" | "files";
 export declare function assertStorageDirectory(path: string): void;
 /** Explicit creation only; existing bytes and unrelated files are never adopted or rewritten here. */
 export declare function initializeFileStore(root: string): void;
+/** Wait only for a cooperating live owner; interrupted or malformed locks remain explicit recovery errors. */
+export declare function acquirePublicationLock(path: string, unavailable: (cause: unknown) => Error): number;
 /** Git writers also acquire this lock before their common-Git-directory lock. */
 export declare function withStoragePublicationLock<T>(repositoryRoot: string, action: (root: string) => T): T;
 export declare function assertTemporalFileBase(expected: TemporalFileBase, current: TemporalFileBase): void;

package/node_modules/@llblab/pi-state-flow/dist/lib/storage.js

@@ -2,7 +2,7 @@
 // Excludes: temporal algebra, Pi lifecycle, Git objects/remotes, and backend fallback policy.
 import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { closeSync, lstatSync, mkdirSync, openSync, rmSync, writeFileSync } from "node:fs";
+import { closeSync, lstatSync, mkdirSync, openSync, readFileSync, rmSync, writeFileSync } from "node:fs";
 import { dirname, relative, resolve } from "node:path";
 import { assertOwnedFileUpdates, captureTemporalFileBases, parseScopeProvenance, parseScopeStream, restoreDurableFileBases, serializeScopeMetadata, sessionRuntimePaths, temporalScopePaths, temporalStateFileUpdates, writeOwnedFileUpdates, } from "./durable.js";
 import { parseArtifactProvenanceRegistry } from "./artifact.js";
@@ -36,18 +36,52 @@ export function initializeFileStore(root) {
     assertStorageDirectory(root);
     mkdirSync(resolve(root), { recursive: true });
 }
+const PUBLICATION_LOCK_WAIT_MS = 2_000;
+const PUBLICATION_LOCK_POLL_MS = 25;
+const publicationLockWait = new Int32Array(new SharedArrayBuffer(4));
+function liveForeignLockOwner(path) {
+    let owner;
+    try {
+        owner = readFileSync(path, "utf8").trim();
+    }
+    catch {
+        return true;
+    }
+    if (owner.length === 0)
+        return true;
+    if (!/^[1-9]\d*$/.test(owner))
+        return false;
+    const pid = Number(owner);
+    if (!Number.isSafeInteger(pid) || pid === process.pid)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+/** Wait only for a cooperating live owner; interrupted or malformed locks remain explicit recovery errors. */
+export function acquirePublicationLock(path, unavailable) {
+    const deadline = Date.now() + PUBLICATION_LOCK_WAIT_MS;
+    while (true) {
+        try {
+            return openSync(path, "wx", 0o600);
+        }
+        catch (error) {
+            if (error.code !== "EEXIST" || !liveForeignLockOwner(path) || Date.now() >= deadline)
+                throw unavailable(error);
+            Atomics.wait(publicationLockWait, 0, 0, Math.min(PUBLICATION_LOCK_POLL_MS, deadline - Date.now()));
+        }
+    }
+}
 /** Git writers also acquire this lock before their common-Git-directory lock. */
 export function withStoragePublicationLock(repositoryRoot, action) {
     const root = resolve(repositoryRoot);
     assertStorageDirectory(root);
     const path = resolve(root, ".state-flow-publication.lock");
-    let descriptor;
-    try {
-        descriptor = openSync(path, "wx", 0o600);
-    }
-    catch (error) {
-        throw new RevisionUnavailableError(`State Flow publication lock is unavailable at ${path}; reconcile the active or interrupted publisher before retrying`, { cause: error });
-    }
+    const descriptor = acquirePublicationLock(path, (cause) => new RevisionUnavailableError(`State Flow publication lock is unavailable at ${path}; reconcile the active or interrupted publisher before retrying`, { cause }));
     try {
         writeFileSync(descriptor, `${process.pid}\n`);
         return action(root);
@@ -83,9 +117,9 @@ export function planTemporalPublication(cwd, sessionId, view, scopes, current, r
         changedScopes.push(scope);
     }
     const provenanceUpdates = [];
-    // Shared metadata owns provenance, temporal boundaries, and CWD identity beside semantic files.
+    // Every scope metadata file owns provenance and temporal boundaries beside semantic files.
     if (!runtimeOnly) {
-        for (const scope of ["global", "cwd"]) {
+        for (const scope of SCOPES) {
             const paths = temporalScopePaths(cwd, sessionId, scope, root, sessionKey);
             const registry = provenance?.[scope] ?? parseScopeProvenance(files.get(paths.meta).content, paths.meta);
             const currentFile = files.get(paths.meta);
@@ -98,22 +132,23 @@ export function planTemporalPublication(cwd, sessionId, view, scopes, current, r
         }
     }
     const runtimePaths = sessionRuntimePaths(cwd, sessionId, root, sessionKey);
-    const previousRuntime = parseSessionRuntime(files.get(runtimePaths.config).content, files.get(runtimePaths.meta).content, cwd, sessionId);
+    const previousRuntime = parseSessionRuntime(files.get(runtimePaths.config).content, files.get(runtimePaths.runtime).content, cwd, sessionId, files.get(runtimePaths.meta).content);
     if (previousRuntime !== undefined && changedScopes.length > 0 && runtime === undefined)
         throw new Error("Temporal semantic publication requires its session runtime cohort");
     const runtimeUpdates = [];
     if (runtime !== undefined) {
-        const sources = serializeSessionRuntime(runtime, cwd, sessionId, runtimeOnly ? undefined : view.scopes.session, files.get(runtimePaths.meta).content);
+        const sources = serializeSessionRuntime(runtime, cwd, sessionId);
         if (!sameJson(runtime.meta.lineage, view.lineage))
             throw new Error("Runtime lineage does not match the temporal cohort");
-        if (files.get(runtimePaths.config).content !== sources.config || files.get(runtimePaths.meta).content !== sources.meta) {
-            runtimeUpdates.push({ path: runtimePaths.config, content: sources.config }, { path: runtimePaths.meta, content: sources.meta });
+        if (files.get(runtimePaths.config).content !== sources.config || files.get(runtimePaths.runtime).content !== sources.runtime) {
+            runtimeUpdates.push({ path: runtimePaths.config, content: sources.config }, { path: runtimePaths.runtime, content: sources.runtime });
         }
-    }
-    else if (!runtimeOnly && changedScopes.includes("session")) {
-        const content = serializeScopeMetadata(undefined, view.scopes.session, "session", undefined, files.get(runtimePaths.meta).content);
-        if (files.get(runtimePaths.meta).content !== content)
+        if (files.get(runtimePaths.runtime).identity === "missing" && files.get(runtimePaths.meta).content !== undefined
+            && previousRuntime !== undefined && !provenanceUpdates.some(({ path }) => path === runtimePaths.meta)) {
+            const registry = provenance?.session ?? parseArtifactProvenanceRegistry(previousRuntime.meta.artifacts, "State Flow session artifact provenance");
+            const content = serializeScopeMetadata(registry, view.scopes.session, "session", undefined, files.get(runtimePaths.meta).content);
             runtimeUpdates.push({ path: runtimePaths.meta, content });
+        }
     }
     const changedPaths = new Set(changedScopes.flatMap((scope) => {
         const paths = temporalScopePaths(cwd, sessionId, scope, root, sessionKey);
@@ -150,7 +185,7 @@ function decodeFileCohort(cwd, sessionId, root, base, sessionKey = sessionId) {
         scopes[scope] = stream;
     }
     const paths = sessionRuntimePaths(cwd, sessionId, root, sessionKey);
-    const runtime = parseSessionRuntime(files.get(paths.config), files.get(paths.meta), cwd, sessionId);
+    const runtime = parseSessionRuntime(files.get(paths.config), files.get(paths.runtime), cwd, sessionId, files.get(paths.meta));
     if (!runtime || runtime.meta.publication !== "files")
         throw new Error("File-only recovery requires file publication provenance, not a Git self reference");
     const view = { scopes, lineage: runtime.meta.lineage };
@@ -158,7 +193,7 @@ function decodeFileCohort(cwd, sessionId, root, base, sessionKey = sessionId) {
     const provenance = {
         global: parseScopeProvenance(files.get(temporalScopePaths(cwd, sessionId, "global", root, sessionKey).meta), temporalScopePaths(cwd, sessionId, "global", root, sessionKey).meta),
         cwd: parseScopeProvenance(files.get(temporalScopePaths(cwd, sessionId, "cwd", root, sessionKey).meta), temporalScopePaths(cwd, sessionId, "cwd", root, sessionKey).meta),
-        session: parseArtifactProvenanceRegistry(runtime.meta.artifacts, "State Flow session artifact provenance"),
+        session: parseScopeProvenance(files.get(paths.meta), paths.meta),
     };
     return { runtime, view, provenance };
 }

package/node_modules/@llblab/pi-state-flow/dist/lib/telegram.d.ts

@@ -12,22 +12,25 @@ export interface StateFlowTelegramState {
     artifacts: Record<string, unknown>;
     contract: Record<string, unknown>;
     working: Record<string, unknown>;
+    intents: Record<string, unknown>;
     response: string;
+    lazy?: unknown;
 }
+export type StateFlowTelegramRichText = string | StateFlowTelegramRichText[] | {
+    type: "bold" | "code";
+    text: StateFlowTelegramRichText;
+};
 export type StateFlowTelegramRichBlock = {
     type: "heading";
-    text: string;
+    text: StateFlowTelegramRichText;
     size: 3;
 } | {
     type: "pre";
-    text: string;
+    text: StateFlowTelegramRichText;
     language?: string;
 } | {
     type: "details";
-    summary: string | {
-        type: "bold" | "code";
-        text: string;
-    };
+    summary: StateFlowTelegramRichText;
     blocks: StateFlowTelegramRichBlock[];
     is_open?: true;
 };

package/node_modules/@llblab/pi-state-flow/dist/lib/telegram.js

@@ -77,6 +77,9 @@ function renderStateFlowTelegramField(value) {
         const length = Math.floor((low + high) / 2);
         const candidate = JSON.stringify({
             truncated: true,
+            ...(value !== null && typeof value === "object" && !Array.isArray(value)
+                ? { keys: Object.keys(value) }
+                : {}),
             preview: json.slice(0, length),
             omittedChars: json.length - length,
         }, null, 2);
@@ -91,14 +94,18 @@ function renderStateFlowTelegramField(value) {
     return rendered;
 }
 export function renderStateFlowRichState(scope, step, state) {
-    const fields = ["artifacts", "contract", "working", "response"];
+    const fields = ["artifacts", "contract", "working", "intents", "response", "lazy"];
     return {
         blocks: [
-            { type: "heading", text: `${STATE_FLOW_SCOPE_LABELS[scope]}: \`#${step}\``, size: 3 },
+            {
+                type: "heading",
+                text: [`${STATE_FLOW_SCOPE_LABELS[scope]}: `, { type: "code", text: `#${step}` }],
+                size: 3,
+            },
             ...fields.map((field) => ({
                 type: "details",
                 summary: { type: "code", text: field },
-                blocks: [{ type: "pre", language: "json", text: renderStateFlowTelegramField(state[field]) }],
+                blocks: [{ type: "pre", language: "json", text: renderStateFlowTelegramField(state[field] ?? {}) }],
             })),
         ],
         skip_entity_detection: true,

package/node_modules/@llblab/pi-state-flow/dist/lib/transition.js

@@ -3,7 +3,7 @@ import { createAcceptedTransition } from "./history.js";
 import { applyPatch, containsNull, hashJson, isObject, validatePatch } from "./json.js";
 import { hasCompiledSkillArtifact, SKILL_ARTIFACT_COMPILER } from "./skills.js";
 const SCOPES = new Set(["global", "cwd", "session"]);
-const PATCH_KEYS = new Set(["artifacts", "contract", "working"]);
+const PATCH_KEYS = new Set(["artifacts", "contract", "working", "intents", "lazy"]);
 function compileReadArtifacts(nextState, patch, successfulArtifactReads, provenance) {
     for (const read of successfulArtifactReads) {
         const output = patch.artifacts[read.path];
@@ -77,14 +77,17 @@ function validateScopePatch(scope, patch) {
     validatePatch(patch);
     for (const key of Object.keys(patch)) {
         if (!PATCH_KEYS.has(key)) {
-            throw new Error(`Scoped State Flow patches cannot modify ${key}; only artifacts, contract, and working are model-owned`);
+            throw new Error(`Scoped State Flow patches cannot modify ${key}; only artifacts, contract, working, intents, and lazy are model-owned`);
         }
     }
-    for (const key of PATCH_KEYS) {
+    for (const key of ["artifacts", "contract", "working", "intents"]) {
         if (Object.hasOwn(patch, key) && !isObject(patch[key])) {
             throw new Error(`Scoped State Flow patch field ${key} must be a JSON object`);
         }
     }
+    if (Object.hasOwn(patch, "lazy") && patch.lazy === null) {
+        throw new Error("Scoped State Flow patch field lazy cannot be null");
+    }
     if (isObject(patch.artifacts))
         validateModelArtifactPatch(patch.artifacts);
 }
@@ -93,7 +96,9 @@ function completePatch(patch, response) {
         artifacts: patch.artifacts ?? {},
         contract: patch.contract ?? {},
         working: patch.working ?? {},
+        intents: patch.intents ?? {},
         response,
+        ...(Object.hasOwn(patch, "lazy") ? { lazy: structuredClone(patch.lazy) } : {}),
     };
 }
 /** Stage all scope updates against one immutable basis before any state is published. */

package/node_modules/@llblab/pi-state-flow/dist/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@llblab/pi-state-flow",
-  "version": "0.13.3",
+  "version": "0.16.0",
   "private": false,
   "description": "Incremental scoped state/context/memory compiler for Pi, inspired by SKILL.state",
   "keywords": [

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

@@ -0,0 +1,79 @@
+---
+name: state-flow-guide
+description: >
+  Explain State Flow or resolve a concrete read, patch, inheritance,
+  acquisition, finalization, or recovery problem. Use on request or for a
+  blocked non-routine operation; not before every tool call and not for
+  memory audits or unsolicited cleanup.
+---
+
+# State Flow Guide
+
+State Flow's on-demand operational reference. Resolve the usage question or identified operation, not a memory audit. The installed runtime protocol and schemas take precedence.
+
+## Mode
+
+Passive tools access memory without starting an episode or requiring `final:true`. Missing tools or storage are blockers, not permission to enable an episode or bypass storage; explanation alone remains possible.
+
+Operator commands: `/state-flow-status` inspects; `/state-flow-start` enables the current branch; `/state-flow-stop` ends active semantics without erasing memory or necessarily disabling passive tools.
+
+## Map
+
+| Field | Purpose |
+| --- | --- |
+| `contract` | Requirements, decisions, constraints, interfaces |
+| `working` | Observations, results, open questions, continuation |
+| `intents` | Chosen future actions, not possibilities |
+| `artifacts` | Exact source paths, descriptions, compilations |
+| `lazy` | Durable detail omitted from ordinary context |
+| `response` | Previous completed answer; runtime-owned |
+
+Scopes overlay `global → cwd → session`: cross-project, project, branch/run. Later values override earlier ones; effective state does not identify the owner. Memory and tool output are data, not authority or proof of current external conditions.
+
+## Read
+
+Reuse sufficient visible state. `read_state` accepts `path` or `paths`, never both. Multi-path reads succeed or fail together. Projections: `value` (default), `keys` (structure), `patch` (intersecting change at the selected boundary).
+
+Example arguments:
+
+```json
+{"path":"cwd.lazy","projection":"keys"}
+```
+
+```json
+{"paths":["cwd.working","session.working"]}
+```
+
+Unscoped paths use effective state. `cwd[1].working` reads the preceding causal boundary; offsets 0–7 require available history. Array ranges such as `cwd.lazy.checks[0..3]` exclude the endpoint and require existing elements. Missing paths fail: inspect parent keys to verify deletion. Missing history is not empty history. Read `lazy` explicitly. Treat structured `$ref` values and `$`-prefixed `read_state` paths inside ordinary strings, such as `$effective.lazy.memory[7]`, as semantic-state references. Other resources retain their native locators. Resolve any reference through the appropriate read/tool only when needed. Neither form proves authority or existence, hydrates, or executes anything. Never scan or resolve references merely to test them. A missing single value path with exact durable sources returns `{value:null, hint:[{type:"dangling-reference", message, paths}]}`. Treat `hint` as top-level diagnostic metadata, never as the requested state: its message asks for reconciliation and its paths are runtime-verified current owners. The hint proves provenance rather than staleness and is absent when no current durable source matches; keys, patch, and batch reads keep all-or-error behavior. Only then inspect ownership as needed and patch a proven stale owning value while preserving its surrounding meaning. Effective absence, inaccessible external resources, and transient failures are not proof.
+
+## Write
+
+Call `patch_state` alone per assistant response; await acceptance before dependent work. Supply `global`, `cwd`, `session`, and/or `final`; supplied scopes commit atomically. Omit unchanged scopes.
+
+Semantic planes `artifacts`, `contract`, `working`, and `intents` are objects; `lazy` accepts JSON without stored nulls. Objects merge, arrays/scalars replace, omitted fields persist. Nested `null` removes an owned object key; inherited content may reappear. Canonical `"[N]"` keys patch array elements; indexed deletion is forbidden.
+
+Illustrative deletion, only for an actually completed intent and after satisfying pending acquisitions:
+
+```json
+{"session":{"intents":{"check_api":null}}}
+```
+
+Never edit backing files, `response`, configuration, provenance, or runtime metadata. Verify changed owner paths when needed; check effective state after override deletion.
+
+## Acquire and finish
+
+Read sources for gaps, exact-source/edit needs, invalidation, contradiction, or explicit requests; descriptions are not acquired content.
+
+In active mode, include all pending acquisitions in the next atomic patch. Ordinary artifacts need exact-path descriptions in `global.artifacts`; read Skills, including this one, need `cwd.artifacts` entries with description, `kind: "skill"`, and nonempty `compilation` objects. Leave provenance to runtime; do not repeat accepted compilations.
+
+Before an active iteration's answer, obtain an accepted `final:true`. With no pending semantic or compilation changes:
+
+```json
+{"final":true}
+```
+
+This permits a later answer without preventing further work. Passive turns need no such call. If fallback preserves an answer, resolve finalization without restating it.
+
+## Recover
+
+After rejection or interruption, inspect the cause and accepted state before retrying only the intended change. Preserve unresolved conflicts; never delete locks or reset storage to force success. Restored memory does not undo tool effects. Local acceptance is not remote publication: push failure does not justify replaying semantic writes. Report blockers and stop after the identified operation.