@hassangameryt/freeflow 0.6.0 → 0.7.1

package/pi-extension/tests/integration/unaffected-regressions.test.js

@@ -0,0 +1,411 @@
+import assert from "node:assert/strict";
+import { execFile } from "node:child_process";
+import { mkdir, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import test from "node:test";
+import { promisify } from "node:util";
+
+import freeflowExtension from "../../dist/index.js";
+import { resetSessionOverrides, setSessionCoreOverride } from "../../dist/runtime/runtime-context.js";
+import { PIFLOW_HOST } from "../cognitive-routing/host-fixture.js";
+
+const execFileAsync = promisify(execFile);
+
+const theme = {
+  fg(_color, text) {
+    return text;
+  },
+  bold(text) {
+    return text;
+  },
+};
+
+function context(cwd, options = {}) {
+  const notifications = [];
+  const reloads = [];
+  const statuses = [];
+  return {
+    cwd,
+    notifications,
+    reloads,
+    statuses,
+    mode: options.mode,
+    hasUI: options.hasUI,
+    isIdle: options.isIdle,
+    async reload() {
+      reloads.push(true);
+    },
+    sessionManager: {
+      getBranch: () => options.entries ?? [],
+      getEntries: () => options.entries ?? [],
+    },
+    ui: {
+      setStatus(name, value) {
+        statuses.push({ name, value });
+      },
+      notify(message, level) {
+        notifications.push({ message, level });
+      },
+    },
+  };
+}
+
+function loadExtension() {
+  const handlers = new Map();
+  const commands = [];
+  const tools = [];
+  const pi = {
+    host: PIFLOW_HOST,
+    registerTool(tool) {
+      tools.push(tool);
+    },
+    registerCommand(name, definition) {
+      commands.push({ name, definition });
+    },
+    registerShortcut() {},
+    on(name, handler) {
+      handlers.set(name, handler);
+    },
+    appendEntry() {},
+    sendUserMessage() {},
+    getAllTools() {
+      return tools.map((tool) => ({ name: tool.name }));
+    },
+    getActiveTools() {
+      return tools.map((tool) => tool.name);
+    },
+    setActiveTools() {},
+  };
+  freeflowExtension(pi);
+  return { handlers, commands, pi };
+}
+
+async function configuredRepo(config = {}) {
+  const cwd = await mkdtemp(join(tmpdir(), "freeflow-unaffected-regressions-"));
+  await mkdir(join(cwd, ".freeflow"));
+  await writeFile(join(cwd, ".freeflow/config.json"), JSON.stringify(config, null, 2), "utf8");
+  return cwd;
+}
+
+function freeflowCommand(commands) {
+  const command = commands.find((candidate) => candidate.name === "freeflow");
+  assert.ok(command);
+  return command;
+}
+
+test("non-TUI settings selectors provide guidance without mutation", async () => {
+  const cwd = await configuredRepo();
+  const configPath = join(cwd, ".freeflow/config.json");
+  const original = await readFile(configPath, "utf8");
+  try {
+    const { commands } = loadExtension();
+    const command = freeflowCommand(commands);
+    const rpc = context(cwd, { mode: "rpc" });
+    rpc.ui.custom = async () => assert.fail("RPC settings must not open the TUI");
+    await command.definition.handler("settings", rpc);
+    assert.match(rpc.notifications.at(-1).message, /require Pi TUI/);
+    assert.equal(await readFile(configPath, "utf8"), original);
+
+    const print = context(cwd, { mode: "json", hasUI: false });
+    await assert.rejects(() => command.definition.handler("settings", print), /require Pi TUI/);
+    assert.equal(await readFile(configPath, "utf8"), original);
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test("settings refuse a mid-run mutation before opening the TUI", async () => {
+  const cwd = await configuredRepo();
+  const configPath = join(cwd, ".freeflow/config.json");
+  const original = await readFile(configPath, "utf8");
+  try {
+    const { commands } = loadExtension();
+    const command = freeflowCommand(commands);
+    const settings = context(cwd, { isIdle: () => false });
+    settings.ui.custom = async () => assert.fail("settings UI must not open while Pi is running");
+    await command.definition.handler("settings repo", settings);
+    assert.match(settings.notifications.at(-1).message, /only while Pi is idle/);
+    assert.equal(await readFile(configPath, "utf8"), original);
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test("settings recheck idle state before committing a master-switch selection", async () => {
+  const cwd = await configuredRepo({ enabled: false });
+  const configPath = join(cwd, ".freeflow/config.json");
+  const original = await readFile(configPath, "utf8");
+  let idle = true;
+  try {
+    const { commands } = loadExtension();
+    const command = freeflowCommand(commands);
+    const settings = context(cwd, { isIdle: () => idle });
+    settings.ui.custom = async (factory) => {
+      let result;
+      const component = factory({ requestRender() {} }, theme, {}, (value) => {
+        result = value;
+      });
+      idle = false;
+      component.handleInput("\r");
+      component.handleInput("\u001b[A");
+      component.handleInput("\r");
+      await component.waitForWrites();
+      component.handleInput("\u001b");
+      return result;
+    };
+    await command.definition.handler("settings repo", settings);
+    assert.match(settings.notifications.at(-1).message, /only while Pi is idle/);
+    assert.equal(await readFile(configPath, "utf8"), original);
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test("personal settings keep repository state unchanged while editing context", async () => {
+  const cwd = await configuredRepo();
+  const configPath = join(cwd, ".freeflow/config.json");
+  const original = await readFile(configPath, "utf8");
+  try {
+    const { commands } = loadExtension();
+    const command = freeflowCommand(commands);
+    const settings = context(cwd);
+    settings.ui.custom = async (factory) => {
+      let result;
+      const component = factory({ requestRender() {} }, theme, {}, (value) => {
+        result = value;
+      });
+      component.handleInput("\u001b[B");
+      component.handleInput("\u001b[B");
+      component.handleInput("\r");
+      component.handleInput("\r");
+      component.handleInput("\u001b[B");
+      component.handleInput("\r");
+      await component.waitForWrites();
+      component.handleInput("\u001b");
+      component.handleInput("\u001b");
+      return result;
+    };
+    await command.definition.handler("settings", settings);
+    assert.equal(await readFile(configPath, "utf8"), original);
+    assert.equal(JSON.parse(await readFile(join(cwd, ".freeflow/local.json"), "utf8")).contextVirtualization, true);
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test("context settings refresh their parent summary after a child changes", async () => {
+  const cwd = await configuredRepo({ contextVirtualization: true });
+  try {
+    const { commands } = loadExtension();
+    const command = freeflowCommand(commands);
+    const settings = context(cwd);
+    settings.ui.custom = async (factory) => {
+      let result;
+      const component = factory({ requestRender() {} }, theme, {}, (value) => {
+        result = value;
+      });
+      assert.match(component.render(120).join("\n"), /Freeflow Context\s+enabled \(2\) 1\/2 enabled/);
+      component.handleInput("\u001b[B");
+      component.handleInput("\u001b[B");
+      component.handleInput("\r");
+      component.handleInput("\r");
+      component.handleInput("\u001b[B");
+      component.handleInput("\u001b[B");
+      component.handleInput("\r");
+      await component.waitForWrites();
+      component.handleInput("\u001b");
+      assert.match(component.render(120).join("\n"), /Freeflow Context\s+disabled \(2\) 0\/2 enabled/);
+      component.handleInput("\u001b");
+      return result;
+    };
+    await command.definition.handler("settings", settings);
+    const local = JSON.parse(await readFile(join(cwd, ".freeflow/local.json"), "utf8"));
+    assert.equal(local.contextVirtualization, false);
+    assert.equal(settings.reloads.length, 1);
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test("repository settings show personal effective sources without changing shared state", async () => {
+  const cwd = await configuredRepo({ contextVirtualization: false });
+  const repositoryPath = join(cwd, ".freeflow/config.json");
+  const localPath = join(cwd, ".freeflow/local.json");
+  try {
+    await writeFile(localPath, JSON.stringify({ contextVirtualization: true }, null, 2), "utf8");
+    const { commands } = loadExtension();
+    const command = freeflowCommand(commands);
+    const settings = context(cwd, { isIdle: () => true });
+    settings.ui.custom = async (factory) => {
+      let result;
+      const component = factory({ requestRender() {} }, theme, {}, (value) => {
+        result = value;
+      });
+      component.handleInput("\u001b[B");
+      component.handleInput("\u001b[B");
+      component.handleInput("\r");
+      assert.match(component.render(120).join("\n"), /Context Virtualization\s+disabled \(effective enabled · local\)/);
+      component.handleInput("\u001b");
+      return result;
+    };
+    await command.definition.handler("settings repo", settings);
+    assert.deepEqual(JSON.parse(await readFile(repositoryPath, "utf8")), { contextVirtualization: false });
+    assert.deepEqual(JSON.parse(await readFile(localPath, "utf8")), { contextVirtualization: true });
+    assert.equal(settings.reloads.length, 0);
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test("Cognitive Routing preset cancellation preserves the previous repository value", async () => {
+  const cwd = await configuredRepo({
+    cognitiveRouting: {
+      enabled: true,
+      profiles: {
+        standard: { provider: "test", model: "model-a", thinkingLevel: "low" },
+        reasoning: { provider: "test", model: "model-b", thinkingLevel: "high" },
+      },
+    },
+  });
+  const original = await readFile(join(cwd, ".freeflow/config.json"), "utf8");
+  try {
+    const { commands } = loadExtension();
+    const command = freeflowCommand(commands);
+    const settings = context(cwd, { isIdle: () => true });
+    settings.modelRegistry = cognitiveRoutingModelRegistry();
+    settings.ui.custom = async (factory) => {
+      let result;
+      const component = factory({ requestRender() {} }, theme, {}, (value) => {
+        result = value;
+      });
+      component.handleInput("\u001b[B");
+      component.handleInput("\r");
+      component.handleInput("\u001b[B");
+      component.handleInput("\r");
+      component.handleInput("\u001b");
+      component.handleInput("\u001b");
+      return result;
+    };
+    await command.definition.handler("settings repo", settings);
+    assert.equal(await readFile(join(cwd, ".freeflow/config.json"), "utf8"), original);
+    assert.equal(settings.reloads.length, 0);
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test("Cognitive Routing settings refresh after enabling the capability", async () => {
+  const cwd = await configuredRepo({
+    cognitiveRouting: {
+      enabled: false,
+      profiles: {
+        standard: { provider: "test", model: "model-a", thinkingLevel: "low" },
+        reasoning: { provider: "test", model: "model-b", thinkingLevel: "high" },
+      },
+    },
+  });
+  try {
+    const { commands } = loadExtension();
+    const command = freeflowCommand(commands);
+    const settings = context(cwd, { isIdle: () => true });
+    settings.modelRegistry = cognitiveRoutingModelRegistry();
+    settings.ui.custom = async (factory) => {
+      let result;
+      const component = factory({ requestRender() {} }, theme, {}, (value) => {
+        result = value;
+      });
+      component.handleInput("\u001b[B");
+      component.handleInput("\r");
+      component.handleInput("\r");
+      component.handleInput("\u001b[A");
+      component.handleInput("\r");
+      await component.waitForWrites();
+      component.handleInput("\u001b");
+      assert.match(component.render(120).join("\n"), /Cognitive Routing\s+enabled \(5\) configured/);
+      component.handleInput("\u001b");
+      return result;
+    };
+    await command.definition.handler("settings repo", settings);
+    const saved = JSON.parse(await readFile(join(cwd, ".freeflow/config.json"), "utf8"));
+    assert.equal(saved.cognitiveRouting.enabled, true);
+    assert.equal(settings.reloads.length, 1);
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test("session settings preserve mandatory prompts through compaction and resume", async () => {
+  const cwd = await configuredRepo();
+  try {
+    const { handlers } = loadExtension();
+    const ctx = context(cwd);
+    const before = await handlers.get("before_agent_start")({ systemPrompt: "base prompt" }, ctx);
+    assert.match(before.systemPrompt, /# Freeflow Interaction Contract/);
+    await handlers.get("session_compact")({ reason: "manual" }, ctx);
+    const afterCompact = await handlers.get("before_agent_start")({ systemPrompt: "base prompt" }, ctx);
+    assert.match(afterCompact.systemPrompt, /# Freeflow Interaction Contract/);
+    await handlers.get("session_start")({ reason: "resume" }, ctx);
+    const afterResume = await handlers.get("before_agent_start")({ systemPrompt: "base prompt" }, ctx);
+    assert.match(afterResume.systemPrompt, /# Freeflow Interaction Contract/);
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test("retired router-shaped configuration remains inert while core activation works", async () => {
+  const cwd = await configuredRepo({ outputRouter: { postToolRouting: "always" } });
+  try {
+    const { handlers } = loadExtension();
+    const ctx = context(cwd);
+    const before = await handlers.get("before_agent_start")({ systemPrompt: "base prompt" }, ctx);
+    assert.match(before.systemPrompt, /# Freeflow Interaction Contract/);
+    assert.doesNotMatch(before.systemPrompt, /Output Router|freeflow_(search|run|batch)/i);
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
+test("remaining session overrides apply without changing repository configuration", async () => {
+  const cwd = await configuredRepo();
+  try {
+    const configPath = join(cwd, ".freeflow/config.json");
+    const original = await readFile(configPath, "utf8");
+    const { pi } = loadExtension();
+    const ctx = context(cwd);
+    await setSessionCoreOverride("contextVirtualization", true, ctx, pi);
+    const state = await import("../../dist/runtime/runtime-context.js").then(({ readCapabilityState }) =>
+      readCapabilityState(cwd, undefined, PIFLOW_HOST),
+    );
+    assert.equal(state.contextVirtualization.effective, true);
+    assert.equal(await readFile(configPath, "utf8"), original);
+    await resetSessionOverrides(ctx, pi);
+  } finally {
+    await rm(cwd, { recursive: true, force: true });
+  }
+});
+
+function cognitiveRoutingModelRegistry() {
+  const models = [
+    { provider: "test", id: "model-a", name: "Model A", reasoning: true },
+    { provider: "test", id: "model-b", name: "Model B", reasoning: true },
+  ];
+  const supported = new Map([
+    ["model-a", new Set(["off", "low", "medium", "high"])],
+    ["model-b", new Set(["off", "low", "medium", "high", "max"])],
+  ]);
+  return {
+    getAvailable() {
+      return models;
+    },
+    find(provider, id) {
+      return models.find((model) => model.provider === provider && model.id === id);
+    },
+    async getApiKeyAndHeaders() {
+      return { ok: true };
+    },
+    clampThinkingLevel(model, level) {
+      return supported.get(model.id)?.has(level) ? level : "off";
+    },
+  };
+}

package/plugin.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+  "name": "freeflow",
+  "version": "0.7.1",
+  "description": "Feedback-based control system for coding agents.",
+  "author": {
+    "name": "Hassan Mohiddin"
+  },
+  "homepage": "https://github.com/hassan-mohiddin/freeflow",
+  "repository": "https://github.com/hassan-mohiddin/freeflow",
+  "license": "MIT",
+  "keywords": [
+    "workflow",
+    "skills",
+    "agents",
+    "feedback-loop",
+    "task-memory",
+    "planning",
+    "verification",
+    "review",
+    "agent-plugins",
+    "gemini",
+    "copilot",
+    "vscode",
+    "cursor",
+    "kiro",
+    "opencode",
+    "hermes"
+  ],
+  "extensions": {
+    "com.github.copilot": {}
+  }
+}

package/runtime/prompts/cognitive-routing.md

@@ -1,9 +1,10 @@
 ## Cognitive Routing Cue
 
-Cognitive Routing changes compute only and governs compute placement across Freeflow methods. Use the latest Runtime State `Control` and `Profile`.
+Cognitive Routing changes compute only; it never changes Workflow ownership or authority. `Control` and `Profile` in the latest Runtime State report current compute state, not Yield, Delegate, `ACT_BOUNDED`, or boundary state. A Runtime State refresh is host context, not a user interruption, and does not end an active route or `ACT_BOUNDED` scope unless contradicted. Recover routing state from visible records; never infer `Boundary state: NONE`.
 
-When Cognitive Routing is active and its skill has not been read in the current context, read it before applying another Freeflow skill or taking task Act.
+- **Manual:** the held profile runs the ordinary unsplit Workflow; do not request switching.
+- **Automatic:** each user interaction begins in Reasoning, which owns conversational and user-facing analysis, discussion, decisions, questions, assessment, and reporting. This work needs no route marker.
 
-Under manual control, use the held profile for the ordinary unsplit Workflow and do not request a switch. Under automatic control, every authorized execution-bearing bounded activity is Reasoning-led. Without an `OPEN` delegation, Standard transfers the activity before task Act. Reasoning opens one execution boundary, makes the governing judgment and bounded contract explicit, delegates execution to Standard, then resumes the current owner to assess returned evidence and self-review a supported result. Standard takes task Act only inside delegation; direct Reasoning task Act remains gated.
+If the full Cognitive Routing skill is not visible, read it before interpreting or acting on the request. Make that read the only environment call; it is not a route transition. If the read fails or is unavailable, stop and report missing context.
 
-Use the discoverable Cognitive Routing skill before opening, acting within, delegating, returning, closing, reopening, recovering, yielding, or switching an automatic execution boundary. A profile change never widens authority or changes the current owner.
+Once visible, follow the skill's boundary-first execution model. Automatic Standard only executes active Yield or Delegate contracts; at every return condition it writes `YIELD HANDOFF` or `RETURN` and switches to Reasoning. Standard never handles substantive user-facing interaction.

package/runtime/prompts/conversation-history.md

@@ -1,3 +1,3 @@
 ## Conversation History Cue
 
-When the next decision requires exact prior conversation evidence absent from active context, use Conversation History instead of reconstructing it from memory. Current user direction, live source truth, and present runtime state remain authoritative over historical evidence.
+When the next decision requires exact prior conversation evidence absent from active context, use Conversation History instead of reconstructing it from memory.

package/runtime/prompts/core.md

@@ -2,12 +2,83 @@
 
 Freeflow is a workflow layer for one active coding agent. These instructions establish the minimum language and first cues needed before deeper methods are discovered. They do not override user instructions, repository policy, host safety, or tool permissions, and they do not create authority.
 
-Use the latest extension-generated Freeflow Runtime State. Earlier mode, capability, control, and profile state is history. Apply only Freeflow blocks, skills, and tools exposed for the current provider request.
+Use the latest Freeflow Runtime State supplied by the host. It refreshes at session start, after context loss, or when displayed state changes; otherwise the existing snapshot may remain visible without re-emission. Treat earlier state as history and use only the Freeflow guidance, skills, and tools exposed for this request.
 
-## Mode
+Freeflow's core guidance and the separate Interaction Contract are always delivered together whenever Freeflow is enabled. The Interaction Contract remains a separately editable prompt fragment; it is not an optional capability.
 
-- `conversation`: answer, discuss, critique, and inspect existing evidence without mutating or deliberately exercising target behavior. Ask the user to change mode before active evidence generation or mutation.
-- `workflow`: use the adaptive Workflow for consequential or mutating work.
-- `strict-workflow`: use the same Workflow with stronger decision, evidence, verification, and checkpoint pressure at high-risk or hard-to-reverse boundaries.
+## Shared Terms
 
-The user chooses mode. Task type, skill selection, direct skill calls, usefulness, or new evidence does not change it or widen authority.
+- **Authority envelope:** the requested outcome, permitted effects, covered active evidence generation, and stop condition established by a direct request or still-valid approval.
+- **Passive observation:** inspecting existing evidence or sources without exercising target behavior or intentionally changing task state.
+- **Active evidence generation:** exercising target behavior to produce new evidence, including tests, reproductions, benchmarks, prototypes, instrumentation, and runtime probes.
+- **Mutation or delivery:** changing the repository, durable task or session, or external state.
+- **Bounded activity:** one coherent unit of discussion, preservation, execution, evidence, or judgment that ends in one assessable result.
+- **Current owner:** the one Freeflow activity responsible for carrying the current bounded activity to an assessable result. Methods, lenses, references, domain guidance, tools, and reviewers may support it without taking ownership automatically.
+- **Slice:** one coherent outcome that may span several bounded activities and methods. Track Work gives it durable identity when task memory is needed.
+- **Evidence boundary:** the strongest claim current direct evidence can support. It is established by the observing mechanism, not by intent, authority, or confidence.
+- **Self-review:** after fresh evidence initially supports a bounded result, the producing agent silently checks that supported state once for alignment, correctness, suitability, and unnecessary complexity before accepting or reusing it. A corrected state receives only the affected recheck. Self-review is not independent review.
+- **Independent review:** separately selected judgment from a context that did not produce the reviewed state. It reports without editing and does not authorize correction.
+- **Checkpoint:** a deliberately selected boundary that dependent work must not cross unresolved. It may require a decision, review, preservation action, or delivery result. An activity ending or work pausing does not create one automatically.
+- **Re-entry:** return only to the narrowest current owner whose responsibility changed, preserving valid work, decisions, and evidence.
+- **Supported Exit:** the justified end of the current Interaction Lifecycle: an evidence-supported answer, wait, pause, handoff, deferment, controlled boundary, stop, or completion, with material limits and unresolved state made explicit.
+
+One Interaction Lifecycle may contain several bounded activities. A Slice may span several bounded activities and methods. Each bounded activity has one current owner and may contain several environment interactions.
+
+## Recover After Context Loss
+
+After compaction, summarization, clear, resume, session navigation, handoff, or uncertain continuity, pause task-directed work. Until recovery is complete, use the environment only for bounded reads needed to recover current state.
+
+Treat summaries, records, prior skill reads, transition results, and historical messages as memory. They may preserve still-valid context and authority, but they do not create or widen authority, prove live state, keep a method active, or settle current ownership. Current user direction, live source truth, and the latest Freeflow Runtime State take precedence when they conflict.
+
+Before continuing:
+
+- Require the latest Freeflow Runtime State. If it is absent, stale, conflicting, or inconsistent with the exposed skills and tools, do not infer it.
+- Read each relevant active capability skill before relying on or changing that capability.
+- When ongoing work has or may have a Working Record, read Track Work and recover its `resume` view before task work.
+- Identify the current owner. Read Workflow when authority, ownership, route, or continuity is unclear, then read the owner’s skill when its exact method is absent.
+- Recover the current Slice, route or execution boundary, blockers, checkpoints, evidence boundary, partial effects, and stop condition without inventing missing state.
+
+Resume only when authority, ownership, current work, route, evidence requirements, and the stop condition are coherent. Otherwise inspect the missing source, ask, defer, or stop.
+
+## Three Nested Loops
+
+One user-facing **Interaction Lifecycle** runs from Entry to a Feedback Loop when needed to a Supported Exit. A later user turn or new evidence begins another lifecycle.
+
+For each bounded activity, the **Feedback Loop** is:
+
+```text
+Orient
+-> choose one current owner
+-> use the current owner
+-> gather or produce evidence
+-> determine what the result proves
+-> self-review the supported result
+-> continue, correct, re-enter, ask, defer, stop, or exit
+```
+
+When the current owner must touch the environment, the **Environment Interaction Loop** is:
+
+```text
+Need evidence or a covered effect
+-> select and bound one environment action
+-> choose the tool
+-> execute once
+-> observe
+-> identify what changed
+-> reconcile observation residency when available
+-> return to the current owner
+```
+
+The Environment Interaction Loop may run zero or more times inside one Feedback Loop. It never changes the current owner or authority by itself.
+
+## Workflow Cue
+
+Workflow owns authority interpretation and enforcement, one current owner for the current bounded activity, evidence-driven re-entry, and Supported Exit. A direct request covers only its bounded outcome and entailed tools, checks, and reversible local choices. Before uncovered active evidence generation, mutation, delivery, or another separately controlled action, state the purpose, action, expected result, and stop condition; ask once and wait. Freeflow guidance, memory, reviews, and new evidence do not grant authority.
+
+## Action Selection Cue
+
+Before an uncertain, broad, or repeated environment interaction, use Action Selection to choose and bound one useful action. Return its observation and state change to the current owner. An obvious mechanical and directly verifiable action takes the fast path without manufactured alternatives.
+
+## Supported Exit
+
+Reach a Supported Exit when current evidence and authority support the reported answer, wait, pause, deferment, controlled boundary, stop, or completion; required self-review and selected checkpoints are resolved where applicable; task memory and required artifacts are accurate; and no material contradiction, source conflict, or user-owned decision remains hidden. Report the outcome, evidence, limits, and current route.

package/runtime/prompts/interaction-contract.md

@@ -2,6 +2,10 @@
 
 Work as a collaborative senior engineer. Read the whole user turn before responding. Treat the user’s goals and choices as theirs, and judge factual and technical claims from evidence: agree when supported, disagree when warranted, state uncertainty plainly, and revise when evidence changes.
 
-Treat questions, criticism, examples, hypotheses, and tentative ideas as discussion. When a turn mixes a direct question with a request or approval to act, answer first and wait for clear authorization. Proceed in the same response only when the user explicitly asks you to answer and then act without waiting.
+Questions, criticism, examples, hypotheses, and tentative ideas do not authorize action by themselves.
 
-With a clear action request, recommend brief discussion only when user input could materially change the outcome, scope, tradeoffs, approach, or acceptance. Otherwise stay within the request and current mode, choose reversible local details, and proceed. Ask before going beyond the request.
+When a turn combines a direct question with a requested action, answer the question first. If the answer leaves the action clear, supported, and explicitly authorized, proceed in the same response. If the answer could change the user’s choice, expose a source conflict, or leave the action conditional, answer and wait.
+
+With a clear action request, recommend brief discussion only when user input could materially change the outcome, scope, tradeoffs, approach, or acceptance. Otherwise stay within the request and current authority envelope, choose reversible local details, and proceed. Ask before going beyond the request.
+
+Use Freeflow terminology in user-facing responses only when it materially improves clarity. Otherwise speak in ordinary engineering language.