@hassangameryt/freeflow 0.4.0 → 0.6.0

package/skills/evaluate-skill/scripts/lib/sandbox.mjs

@@ -69,6 +69,98 @@ export async function materializeFixture({ fixture, workspace }) {
   return { ...fixture, materializedPath };
 }
 
+export async function prepareRuntime({ runtime, root, groupDirectory }) {
+  const canonicalRoot = await realpath(root);
+  const runtimeRoot = path.join(groupDirectory, "resources", "runtime", "extensions");
+  await mkdir(runtimeRoot, { recursive: true });
+  const bundles = [];
+
+  for (const [index, bundle] of runtime.extensions.entries()) {
+    const bundleRoot = path.join(runtimeRoot, String(index));
+    await mkdir(bundleRoot, { recursive: true });
+    const resources = [];
+    for (const declaredPath of bundle.resources) {
+      resources.push(
+        await snapshotWorkingTreeResource({
+          canonicalRoot,
+          declaredPath,
+          destination: path.join(bundleRoot, declaredPath),
+          requireDirectory: true,
+          label: "runtime resource",
+        }),
+      );
+    }
+    const root = await realpath(bundleRoot);
+    const entry = await realpath(path.join(root, bundle.entry)).catch(() => null);
+    if (entry === null || !isContained(root, entry)) {
+      throw new Error(`declared runtime entry is missing or escapes its bundle: ${bundle.entry}`);
+    }
+    const entryStat = await lstat(entry);
+    if (!entryStat.isFile()) throw new Error(`declared runtime entry is not a file: ${bundle.entry}`);
+    if (!resources.some((resource) => isContained(resource.path, entry))) {
+      throw new Error(`declared runtime entry is not contained by a resource: ${bundle.entry}`);
+    }
+    bundles.push({
+      entry,
+      root,
+      resources,
+    });
+  }
+
+  return {
+    host: runtime.host,
+    session: runtime.session,
+    environment: { ...runtime.environment },
+    extensions: bundles,
+  };
+}
+
+export async function materializeRuntime({ runtime, variantDirectory }) {
+  const runtimeRoot = path.join(variantDirectory, "resources", "runtime", "extensions");
+  await mkdir(runtimeRoot, { recursive: true });
+  const bundles = [];
+
+  for (const [index, bundle] of runtime.extensions.entries()) {
+    const destination = path.join(runtimeRoot, String(index));
+    await cp(bundle.root, destination, {
+      recursive: true,
+      dereference: false,
+      errorOnExist: true,
+      force: false,
+    });
+    const root = await realpath(destination);
+    const resources = [];
+    for (const resource of bundle.resources) {
+      const resourceRoot = await realpath(path.join(root, resource.declaredPath));
+      const files = await fingerprintDirectory(resourceRoot);
+      if (JSON.stringify(files) !== JSON.stringify(resource.files)) {
+        throw new Error(`declared runtime resource changed while being copied: ${resource.declaredPath}`);
+      }
+      resources.push({ ...resource, path: resourceRoot, files });
+    }
+    const entry = await realpath(path.join(root, path.relative(bundle.root, bundle.entry)));
+    bundles.push({ ...bundle, entry, root, resources });
+  }
+
+  return {
+    host: runtime.host,
+    session: runtime.session,
+    environment: { ...runtime.environment },
+    extensions: bundles,
+  };
+}
+
+export async function verifyRuntime(runtime) {
+  for (const bundle of runtime.extensions) {
+    for (const resource of bundle.resources) {
+      const current = await fingerprintDirectory(resource.path);
+      if (JSON.stringify(current) !== JSON.stringify(resource.files)) {
+        throw new Error(`declared runtime resource changed during subject execution: ${resource.declaredPath}`);
+      }
+    }
+  }
+}
+
 export async function materializeEnvironment({ environment, root, variantDirectory }) {
   const canonicalRoot = await realpath(root);
   let source;

package/skills/evaluate-skill/scripts/pi-guard.mjs

@@ -15,7 +15,7 @@ function parseStringArray(value) {
 
 function isContained(root, target) {
   const relative = path.relative(root, target);
-  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+  return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
 }
 
 function resolveWritablePath(cwd, requested) {

package/skills/evaluate-skill/scripts/pi-observer.mjs

@@ -0,0 +1,66 @@
+import { appendFileSync } from "node:fs";
+
+const outputPath = process.env.SKILL_EVAL_CONTEXT_OBSERVATION_PATH;
+let turn = 0;
+let requestInTurn = 0;
+let providerRequest = 0;
+
+function textFromContent(content) {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return content
+    .map((block) => {
+      if (!block || typeof block !== "object") return "";
+      if (block.type === "text" && typeof block.text === "string") return block.text;
+      if (block.type === "image" && typeof block.mimeType === "string") return `[image:${block.mimeType}]`;
+      return "";
+    })
+    .filter(Boolean)
+    .join("\n");
+}
+
+function append(event) {
+  if (!outputPath) return;
+  appendFileSync(outputPath, `${JSON.stringify({ timestamp: new Date().toISOString(), turn, ...event })}\n`, "utf8");
+}
+
+export default function skillEvaluationObserver(pi) {
+  pi.on("before_agent_start", (event, ctx) => {
+    turn += 1;
+    requestInTurn = 0;
+    const systemPrompt =
+      typeof event?.systemPrompt === "string" ? event.systemPrompt : String(ctx?.getSystemPrompt?.() ?? "");
+    append({
+      kind: "context",
+      surface: "system-prompt",
+      prompt: typeof event?.prompt === "string" ? event.prompt : null,
+      characters: systemPrompt.length,
+      text: systemPrompt,
+      systemPrompt,
+    });
+  });
+
+  pi.on("context", (event) => {
+    providerRequest += 1;
+    requestInTurn += 1;
+    const messages = Array.isArray(event?.messages) ? event.messages : [];
+    const normalized = messages.map((message) => ({
+      role: message?.role ?? null,
+      toolName: message?.toolName ?? null,
+      text: textFromContent(message?.content),
+    }));
+    const text = normalized
+      .map((message) => message.text)
+      .filter(Boolean)
+      .join("\n");
+    append({
+      kind: "context",
+      surface: "provider-context",
+      providerRequest,
+      requestInTurn,
+      characters: text.length,
+      text,
+      messages: normalized,
+    });
+  });
+}

package/skills/evaluate-skill/scripts/skill-eval.mjs

@@ -34,8 +34,9 @@ Selection:
 Current run support:
   Description and explicit-body groups with prompt or ordered turns
   Working-tree or Git-backed ordered skills/context; optional fresh fixture copies
-  Description tools: read; body tools: read, write, edit
-  Deterministic reads, paths, changed paths, text, JSON, and factual comparisons
+  Description tools: read; body tools: read, write, edit, or declared extension tools
+  Runtime profiles: Pi or PiFlow hosts, ordered immutable extension bundles, environment overrides
+  Deterministic reads, paths, changed paths, text, JSON, tool calls, context observations, and factual comparisons
   Ordered suites run serially and continue after isolated variant, group, or post-processing failures
   Grade-first views show compact criterion details, usage, and result-relative artifact paths
 `,
@@ -71,9 +72,7 @@ function parseOperation(values) {
 
 if (!command || command === "--help" || command === "-h") {
   printUsage();
-} else if (!commands.has(command)) {
-  fail(`Unknown command: ${command}`);
-} else {
+} else if (commands.has(command)) {
   try {
     const operation = parseOperation(argv.slice(1));
     if (command === "view") {
@@ -98,4 +97,6 @@ if (!command || command === "--help" || command === "-h") {
   } catch (error) {
     fail(error instanceof Error ? error.message : String(error), 1);
   }
+} else {
+  fail(`Unknown command: ${command}`);
 }

package/skills/execute-work/SKILL.md

@@ -5,28 +5,28 @@ description: Use when executing or resuming implementation, fixes, prototypes, d
 
 # Execute Work
 
-Carry out concrete work through bounded actions and fresh evidence only when it was requested or approved and the effective mode permits mutation.
+Carry out concrete work through bounded actions and fresh evidence only when it was requested or approved and the effective mode permits its effects.
 
-A **slice** is one coherent result tracked and reviewed as a unit. A **bounded action** is one implementation, experiment, correction, or observation inside that slice. One slice may span multiple Feedback Loop iterations and owning skills while its intended result remains coherent.
+A Slice is the shared coherent outcome. Execute Work owns each **bounded action**—one implementation, experiment, correction, or observation—inside it. A Slice need not have durable task memory; when one does, Track Work records its Current Slice.
 
-Read [the execution loop](references/execution-loop.md) when work spans multiple actions or slices, resumes from prior state, needs a specialized method, reaches a checkpoint, or reveals follow-on work.
+Read [Execute Work edges](references/execute-work-edges.md) when work resumes from prior state, crosses a Slice boundary, reaches a selected checkpoint, or reveals separately controlled follow-on work.
 
 ## Follow The Execution Route
 
 Use this as a directed map, not a fixed phase sequence:
 
 ```text
-[Requested or approved concrete work; effective mode permits mutation]
+[Requested or approved concrete work; effective mode permits its effects]
 -> [Orient and establish the current slice]
 -> [Take one bounded action]
 -> [Test or observe]
 -> [Verify what the evidence proves]
    -> clear local defect -> correct -> test or observe again
    -> unclear, repeated, or route-changing result -> Workflow
-   -> supported -> silent self-review -> freeze
+   -> supported -> silent self-review -> freeze before acceptance or reuse
 -> [Route]
    -> more accepted work in this slice -> next bounded action
-   -> coherent boundary extension -> approve and record when needed -> next action
+   -> coherent boundary extension -> Workflow -> covered and recorded when needed -> next action
    -> distinct result, authority, or evidence boundary -> Workflow
    -> approved checkpoint due -> owning skill -> route again
    -> supported exit -> report
@@ -40,10 +40,10 @@ Establish:
 
 - intended result and the source that supports it;
 - current slice, accepted scope, and relevant live state;
+- the current authority envelope, due checkpoints, and separately controlled boundaries;
 - direct check or observation that can disagree with the result;
-- stop conditions, due checkpoints, and authority boundaries.
 
-A clear user request can be enough. A small self-contained change needs no Spec, Plan, or Working Record merely because execution was selected.
+Execute Work inherits the authority envelope established by Workflow; selecting this method does not create execution authority. A small self-contained change needs no Spec, Plan, or Working Record merely because execution was selected.
 
 Inspect relevant code, tests, docs, policies, artifacts, repository state, and current external constraints before relying on memory. When sources materially conflict or the intended result is unsafe to infer, return the evidence to [Workflow](../workflow/SKILL.md) rather than choosing silently.
 
@@ -56,11 +56,14 @@ Choose the smallest coherent action that can produce the intended result or usef
 - keep unrelated and later work outside it;
 - choose reversible local details from repository conventions;
 - let an experiment fail safely and preserve its discard, revise, or promote condition;
+- keep every experiment and observation inside the authority envelope;
 - use only specialized methods and domain guidance that the concrete boundary needs.
 
+When several environment actions or observers could produce useful evidence, or the likely action is broad, use [Action Selection](../action-selection/SKILL.md) to choose and bound one interaction. Execute Work keeps ownership of the intended result and accepted effects; Action Selection returns the observation or bounded effect. Skip it when the next action is already known, mechanical, and directly verifiable.
+
 When an accepted behavior change, bug correction with a supported cause, consequential rule, or behavior-preserving refactor benefits from a failing check first, use [TDD](../tdd/SKILL.md) for that bounded action before changing production behavior.
 
-Before work changes the intended result, scope, authority, evidence boundary, or stop conditions, decide through Workflow whether it is an accepted extension or a new slice. When a Working Record exists, use Track Work to record an accepted extension before executing it. Do not let a series of “small” additions silently replace the original result.
+Before work changes the intended result, scope, permitted effects, evidence boundary, stop condition, or authority source, decide through Workflow whether it is an accepted extension or a new slice. When a Working Record exists, use Track Work to record an accepted extension before executing it. Do not let a series of “small” additions silently replace the original result.
 
 ## Execute For The Required Boundary
 
@@ -68,21 +71,21 @@ Match implementation and evidence to the work. Code may need behavior tests or r
 
 Do not rewrite tests, checks, Specs, Plans, policies, or accepted behavior merely to make implementation pass. Determine whether the implementation, evidence, environment, or source is wrong before changing what defines success.
 
-When writing or changing code, read [Code Practices](references/code-practices.md). Prefer clear ownership, names, and failure behavior. Comment only non-obvious rationale, constraints, invariants, or temporary behavior with a real exit condition.
+Before writing or changing code, read [Code Practices](references/code-practices.md). Prefer clear ownership, names, and failure behavior. Comment only non-obvious rationale, constraints, invariants, or temporary behavior with a real exit condition.
 
 Handle an edge case only when accepted behavior, observed evidence, or material safety requires it. If expected behavior is undefined and would change observable behavior or scope, return it to Workflow. When related patches keep adding states, flags, or caller coordination, stop and return the shared pressure rather than extending the patch stream.
 
 ## Close Each Evidence Iteration
 
-After each meaningful bounded action:
+After every bounded action:
 
 1. run the focused tests or observations appropriate to its claim;
 2. use [Verify Work](../verify-work/SKILL.md) when the claim or observing boundary needs its fuller method;
-3. when supported, use [Review Work](../review-work/SKILL.md) for silent self-review;
-4. correct clear local issues within existing authority and re-verify;
-5. freeze the supported state and return route-changing evidence to Workflow.
+3. once initial evidence supports the result, use [Review Work](../review-work/SKILL.md) for silent self-review;
+4. correct clear local issues within existing authority and re-verify the affected boundary;
+5. confirm the final state has no unresolved material issue, freeze it, and only then accept, reuse, or report the result.
 
-A failed or inconclusive check does not prove the design or source is wrong. Correct a clear local defect; use [Diagnose Failure](../diagnose-failure/SKILL.md) when the cause is unclear or failure repeats.
+Self-review remains inside the bounded action rather than creating another action or review cycle. A failed or inconclusive check does not prove the design or source is wrong. Correct a clear local defect; use [Diagnose Failure](../diagnose-failure/SKILL.md) when the cause is unclear or failure repeats.
 
 Further polish, advisory warnings, unrelated issues, and review findings without mutation authority are feedback to classify, not permission to keep editing.
 

package/skills/execute-work/references/code-practices.md

@@ -1,6 +1,6 @@
 # Code Practices
 
-Read this when an Execute Work slice writes or changes code. Follow the repository's language, style, testing, and documentation conventions before generic advice.
+Read this before an Execute Work slice writes or changes code. Follow the repository's language, style, testing, and documentation conventions before generic advice.
 
 ## Make Intent Legible
 

package/skills/execute-work/references/execute-work-edges.md

@@ -0,0 +1,42 @@
+# Execute Work Edges
+
+Read this after [Execute Work](../SKILL.md) when work resumes from prior state, crosses a Slice boundary, reaches a selected checkpoint, or reveals separately controlled follow-on work. Execute Work owns the normal action, evidence, method, and continuation loop; this reference covers exceptional transitions.
+
+## Resume Safely
+
+Reopen the source that established the work and inspect live state. When durable task memory exists, request the bounded `resume` view through [Track Work](../../track-work/SKILL.md), then retrieve exact entities only when the next decision needs them.
+
+Re-establish authority from the current conversation and still-valid approval. A summary, Plan, Handoff, Working Record, or another conversation branch preserves context but does not create current authority or prove progress.
+
+Preserve supported work and resume the same Slice only while its intended result, authority, evidence boundary, and stop condition remain coherent. Otherwise return the changed boundary to [Workflow](../../workflow/SKILL.md).
+
+## Cross A Slice Boundary Deliberately
+
+Before beginning a distinct result, independently useful evidence boundary, uncovered effect, changed strategy, or separately controlled action:
+
+1. stop the current action stream;
+2. preserve the supported result and live evidence;
+3. return the boundary change to Workflow;
+4. reconcile the current Slice through Track Work when one exists;
+5. begin another Slice only after its outcome and authority are established.
+
+A verification run, self-review, review report, method change, or pause does not create or close a Slice by itself.
+
+## Route A Selected Checkpoint
+
+When an approved checkpoint becomes due, stop before dependent work, use its owner, and return the result to Workflow. If its condition no longer holds, return the deviation instead of forcing the checkpoint.
+
+A checkpoint result may support continuation, correction, another route, deferment, or stopping. It does not authorize the next lifecycle stage. Track Work preserves selected and resolved checkpoint state when durable memory exists.
+
+## Separate Follow-On Work
+
+Use the owning method only after Workflow confirms its boundary and authority:
+
+- [Commit Work](../../commit-work/SKILL.md) for an authorized local checkpoint or simple push;
+- [Migration Work](../../migration-work/SKILL.md) for accepted consumer, state, or traffic movement;
+- [Finish Branch](../../finish-branch/SKILL.md) for integration, preservation, discard, or cleanup;
+- [Release Work](../../release-work/SKILL.md) for versioned publication;
+- [Launch Work](../../launch-work/SKILL.md) for production exposure or recovery;
+- [Handoff](../../handoff/SKILL.md) for point-in-time continuation transfer.
+
+A useful follow-on result is not implicit authority. Return to Workflow when its scope, evidence, destination, or stop condition is not already covered.

package/skills/finish-branch/SKILL.md

@@ -23,7 +23,7 @@ Before offering or executing a route, inspect:
 
 Do not infer the base, remote destination, pull-request target, or workspace owner when the wrong choice could lose work or affect collaborators.
 
-Read [integration options](references/integration-options.md) when choosing local integration, pull request, preservation, discard, or cleanup. Use [Commit Work](../commit-work/SKILL.md) when the selected route requires a local commit or simple push; do not commit merely to make branch status look finished.
+After inspecting branch, base, remote, dirty state, verification, and workspace ownership, read [integration options](references/integration-options.md) before choosing local integration, pull request, preservation, discard, or cleanup. Use [Commit Work](../commit-work/SKILL.md) when the selected route requires a local commit or simple push; do not commit merely to make branch status look finished.
 
 Use [Release Work](../release-work/SKILL.md) for a separately approved versioned release and [Launch Work](../launch-work/SKILL.md) for a separately approved production deployment or rollout.
 
@@ -99,7 +99,7 @@ Do not run destructive reset, clean, branch deletion, worktree removal, remote d
 
 Resolve a conflict locally only when both sides' intended behavior is settled and the resolution is mechanical. Return behavior, source-truth, API, data, security, compatibility, or architecture conflicts to [Workflow](../workflow/SKILL.md).
 
-Use [Diagnose Failure](../diagnose-failure/SKILL.md) when integrated checks fail without a supported cause. Return mixed or unrelated branch contents to [Commit Work](../commit-work/SKILL.md) and [staging decisions](../commit-work/references/staging-decisions.md). Preserve branch state before re-entering another owning activity.
+Use [Diagnose Failure](../diagnose-failure/SKILL.md) when integrated checks fail without a supported cause. Return mixed or unrelated branch contents to [Commit Work](../commit-work/SKILL.md), which owns staging decisions. Preserve branch state before re-entering another owning activity.
 
 ## Report The Chosen Outcome
 

package/skills/finish-branch/references/integration-options.md

@@ -1,6 +1,6 @@
 # Integration Options
 
-Use this after inspecting branch, base, remote, dirty state, verification, and workspace ownership.
+Read this after inspecting branch, base, remote, dirty state, verification, and workspace ownership and before choosing local integration, pull request, preservation, discard, or cleanup.
 
 ## Local Integration
 

package/skills/handoff/SKILL.md

@@ -19,7 +19,7 @@ A handoff is memory, not authority. It may record where approval or authority ca
 
 Do not silently promote ephemeral context into repository memory. Ask one direct question when the destination changes durability, privacy, repository state, intended audience, or authority and the user has not chosen.
 
-Read [handoff templates](references/templates.md) after the transfer shape and recipient are clear.
+Read [Handoff Templates](references/handoff-templates.md) after the transfer shape, recipient, and purpose are clear.
 
 ## Prepare From Live State
 
@@ -77,8 +77,8 @@ Stop when safe transfer would require inventing intent, authority, evidence, des
 
 When resuming:
 
-1. Reopen the named source truth, Working Record when present, and current worktree state.
-2. Verify important completion, evidence, review, commit, and artifact-identity claims before repeating them.
+1. Reopen the named source truth, the Working Record's bounded `resume` view when present, and current worktree state.
+2. Retrieve exact Working Record entities only when needed, then verify important completion, evidence, review, commit, and artifact-identity claims before repeating them.
 3. Compare the recorded route, decisions, and assumptions with live evidence.
 4. Preserve what still holds and identify only the invalidated layer.
 5. Return the live state and supported next action to [Workflow](../workflow/SKILL.md).

package/skills/launch-work/SKILL.md

@@ -15,7 +15,7 @@ Loading this skill, preparing launch options, or approving a general implementat
 
 Use [Decision Gate](../decision-gate/SKILL.md) when deployment, exposure, rollback, destructive migration, launch window, acceptable degradation, user communication, or recovery direction remains a user-owned choice.
 
-Read [launch readiness](references/launch-readiness.md) when selecting risk lenses, operational evidence, rollout stages, or recovery checks. Use [Release Work](../release-work/SKILL.md) when a versioned artifact must be published first. Use [Migration Work](../migration-work/SKILL.md) when the launch transitions data, traffic, consumers, configuration, or compatibility contracts between old and replacement paths with migration or removal obligations.
+Before selecting risk lenses, operational evidence, rollout stages, or recovery checks, read [launch readiness](references/launch-readiness.md). Use [Release Work](../release-work/SKILL.md) when a versioned artifact must be published first. Use [Migration Work](../migration-work/SKILL.md) when the launch transitions data, traffic, consumers, configuration, or compatibility contracts between old and replacement paths with migration or removal obligations.
 
 ## Define The Launch Contract
 

package/skills/launch-work/references/launch-readiness.md

@@ -1,6 +1,6 @@
 # Launch Readiness
 
-Use only the lenses relevant to the production change. This is not a universal checklist.
+Read this before selecting risk lenses, operational evidence, rollout stages, or recovery checks. Use only the lenses relevant to the production change; this is not a universal checklist.
 
 ## Identity And Ownership
 
@@ -34,7 +34,7 @@ When Workflow selects a security-focused review, read the [security risk lens](.
 - Critical latency, throughput, saturation, queue, storage, and dependency limits have evidence.
 - Advance and abort criteria are relative to accepted SLOs, historical baseline, or owner-approved thresholds.
 
-Read [performance evidence](../../verify-work/references/performance-evidence.md) for readiness and improvement claims. Read [flaky and performance diagnosis](../../diagnose-failure/references/flaky-and-performance.md) only when a regression lacks a supported cause.
+Read [performance evidence](../../verify-work/references/performance-evidence.md) for readiness and improvement claims. Read [Flaky and Performance Diagnosis](../../diagnose-failure/references/flaky-and-performance-diagnosis.md) only when a regression lacks a supported cause.
 
 ## Accessibility And User Experience
 

package/skills/migration-work/SKILL.md

@@ -26,6 +26,8 @@ When replacement behavior, interfaces, ownership, or failure semantics remain un
 
 ## Define The Migration Contract
 
+Before choosing migration shape or units, compatibility, cutover evidence, rollback or forward recovery, or removal proof, read [the migration lifecycle](references/migration-lifecycle.md). Use only the stages required by the accepted migration; do not force every migration through one sequence.
+
 Before moving anything, establish:
 
 ```text
@@ -42,8 +44,6 @@ Owner decisions and stop conditions:
 Approved stages and scope:
 ```
 
-Read [the migration lifecycle](references/migration-lifecycle.md) when choosing an API, code, configuration, dependency, feature, traffic, or data shape. Use only the stages required by the accepted migration; do not force every migration through one sequence.
-
 Treat undocumented observable behavior as a possible consumer dependency until evidence says otherwise. Do not preserve every quirk automatically; surface consequential differences for decision.
 
 ## Prepare The Replacement

package/skills/migration-work/references/migration-lifecycle.md

@@ -1,6 +1,6 @@
 # Migration Lifecycle
 
-Read this when choosing migration units, compatibility shape, cutover evidence, rollback, or removal proof.
+Read this before choosing migration shape or units, compatibility, cutover evidence, rollback or forward recovery, or removal proof.
 
 ## Migration Shapes
 

package/skills/mode-contract/SKILL.md

@@ -7,7 +7,7 @@ description: Use when choosing, changing, or explaining how Freeflow mode applie
 
 Apply the effective Freeflow mode without inferring a different mode from the task. Freeflow has exactly three mode values: `conversation`, `workflow`, and `strict-workflow`.
 
-A mode changes how work proceeds; it does not authorize work, resolve a user-owned decision, or override live evidence.
+A mode changes how work proceeds; it does not authorize work, widen the current authority envelope, resolve a user-owned decision, or override live evidence.
 
 ## Establish The Active Mode
 
@@ -27,15 +27,15 @@ Task shape does not change mode. A question during Workflow stays in Workflow; a
 
 ### Conversation
 
-Answer, discuss, critique, explore, and perform requested read-only inspection.
+Answer, discuss, critique, explore, and inspect existing evidence or sources without exercising target behavior or intentionally changing task state.
 
-Do not mutate files, repository state, external systems, or durable artifacts. If the user requests mutation, explain the boundary and ask them to switch to `workflow` or `strict-workflow` through the host's mode control before proceeding.
+Conversation permits passive observation only for task work. Active evidence generation and mutation or delivery require `workflow` or `strict-workflow` plus authority. If the user requests one, explain the mode boundary and ask them to switch through the host's mode control before proceeding.
 
 Ask only what the answer needs. Conversation mode does not require workflow artifacts, checkpoints, plans, specs, or independent review.
 
 ### Workflow
 
-Use the adaptive [Workflow](../workflow/SKILL.md) for consequential or mutating work. Inspect or ask when ambiguity changes the next action, create durable artifacts only when they preserve needed state or decisions, and verify claims against fresh evidence.
+Use the adaptive [Workflow](../workflow/SKILL.md) for active evidence generation and consequential or mutating work. Inspect or ask when ambiguity changes the next action, create durable artifacts only when they preserve needed state or decisions, and verify claims against fresh evidence.
 
 Workflow mode does not itself authorize a slice or require every lifecycle phase.
 
@@ -55,27 +55,49 @@ The user owns mode changes. Recommend `strict-workflow` when risk warrants it, b
 
 A task type, risk classification, direct skill call, or workflow route does not switch mode. Invoking an execution skill during Conversation still does not authorize mutation.
 
-Use host-native mode control when available. In Pi:
+Use host-managed session control so the change takes effect before the model acts. A clear natural-language instruction may use the same control. Questions, examples, hypotheses, and tentative language do not change mode.
 
 ```text
-/freeflow mode
+Switch to conversation mode.                 -> session override
+Use strict-workflow for this session.         -> session override
+Should we switch to strict-workflow?          -> answer or discuss; no override
+Suppose the mode were conversation.           -> discussion; no override
+```
+
+Host-native controls are:
+
+```text
+Pi:
 /freeflow mode conversation
 /freeflow mode workflow
 /freeflow mode strict-workflow
 /freeflow mode reset
+
+Claude:
+/freeflow:mode-contract <conversation|workflow|strict-workflow|reset>
+
+Codex:
+$mode-contract <conversation|workflow|strict-workflow|reset>
 ```
 
-Pi handles these commands before the model runs. The three setting commands create a session override; `reset` clears it and returns to the configured default, including a personal override when present. `/freeflow mode` inspects or selects mode according to host UI support.
+Claude and Codex persist their override in plugin-owned session state keyed by the host session identifier. Pi persists it in branch-aware Pi session state. The override survives ordinary turns and supported resume, clear, and compact boundaries for that session; `reset` clears it and returns to the configured default. A new session starts from configured state.
 
-For a natural-language request to change Pi session mode, direct the user to the native command. Do not claim runtime state changed until the host reports the new effective mode.
+Treat only runtime-reported effective state as proof that the control succeeded. If the host reports missing session identity, unavailable writable plugin state, disabled Skills, or another failure, say that mode did not change. Do not compensate by editing a configured default.
 
 Mention mode only when the user asks, configuration is being discussed, or it changes the next action.
 
 ## Change Defaults Separately
 
-A persistent default change is not a session-mode change. An unqualified personal default request targets `.freeflow/local.json`; changing the shared repository default requires explicit repository, team, or shared-default wording.
+A persistent default change is not a session-mode change. Determine which configured layer the user means before editing:
+
+- explicit **personal** or **local** default targets `.freeflow/local.json`;
+- explicit **shared**, **repository**, or **team** default targets `.freeflow/config.json`;
+- an unqualified “change the default mode” request leaves that scope user-owned—ask one direct local-versus-repository question and wait;
+- “global” is not a defined Freeflow layer—ask whether the user means this checkout's personal default or the shared repository default.
+
+Do not infer the target from which file already exists or from the current mode. Preserve unrelated settings in the selected layer.
 
-In Pi, use `/freeflow mode` or `/freeflow settings session` for a temporary mode override, `/freeflow settings` for personal overrides, and `/freeflow settings repo` for shared defaults. In another host, use its native settings when available or update only the explicitly selected valid layer while preserving unrelated settings.
+In Pi, `/freeflow settings` edits personal overrides and `/freeflow settings repo` edits shared defaults. In another host, an agent may update only the explicitly selected valid configuration layer. Session controls never modify either file.
 
 For agent-performed config edits, obey the effective mode when one exists. Conversation remains read-only. When no mode is effective because Freeflow is unconfigured, inactive, blocked by invalid config, or Skills are dormant, an explicit configuration or [Setup Freeflow](../setup-freeflow/SKILL.md) request governs the selected change; any dormant resolved mode is neither authority nor prohibition. User-operated host controls change their own state before the model continues.
 

package/skills/release-work/SKILL.md

@@ -22,7 +22,7 @@ Use [Decision Gate](../decision-gate/SKILL.md) when the route depends on an unre
 - yanking, deprecating, replacing, or republishing an artifact;
 - release branches, history rewriting, or recovery from partial publication.
 
-Do not impose semantic versioning when the project uses another scheme. Read [release evidence](references/release-evidence.md) when version, source, artifact, tag, publication, or recovery identity matters.
+Do not impose semantic versioning when the project uses another scheme. Before defining or changing version, source, artifact, tag, publication, or recovery identity, read [release evidence](references/release-evidence.md).
 
 ## Define The Release Contract
 

package/skills/release-work/references/release-evidence.md

@@ -1,6 +1,6 @@
 # Release Evidence
 
-Read this when version, source, artifact, tag, publication, or recovery identity matters.
+Read this before defining or changing version, source, artifact, tag, publication, or recovery identity.
 
 ## Version Basis