@hassangameryt/freeflow 0.5.0 → 0.7.0

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/runtime/prompts/cognitive-routing.md

@@ -0,0 +1,10 @@
+## Cognitive Routing Cue
+
+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`.
+
+- **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.
+
+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.
+
+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/context-virtualization.md

@@ -0,0 +1,3 @@
+## Context Virtualization Cue
+
+After broad or noisy tool evidence has been safely narrowed, exhausted, or crossed a meaningful activity boundary, use Context Virtualization to keep necessary evidence active and archive residue. Do not archive governing context or exact evidence still needed by current work.

package/runtime/prompts/conversation-history.md

@@ -0,0 +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.

package/runtime/prompts/core.md

@@ -0,0 +1,84 @@
+# Freeflow Stable Guidance
+
+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 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.
+
+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.
+
+## Shared Terms
+
+- **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

@@ -0,0 +1,11 @@
+# Freeflow Interaction Contract
+
+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.
+
+Questions, criticism, examples, hypotheses, and tentative ideas do not authorize action by themselves.
+
+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.

package/skills/action-selection/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: "action-selection"
+description: "Use when the current owner needs to choose, bound, or learn from an environment interaction, especially when several actions are plausible, expected output may be broad or noisy, or recent interactions have not materially changed the current decision."
+---
+
+# Action Selection
+
+Choose one covered environment interaction likely to advance the current question or accepted outcome, learn from its actual result, and return the changed evidence to the current owner.
+
+An **environment interaction** is one bounded tool-mediated observation or effect and the result it returns. A bounded activity may contain several environment interactions.
+
+Action Selection does not choose the current owner, execution method, accepted behavior, authority, Slice, checkpoint, or Workflow route. It does not replace implementation, diagnosis, verification, review, or domain guidance.
+
+## Run One Interaction Loop
+
+```text
+Need evidence or a covered effect
+-> name what this interaction must resolve or produce
+-> check whether current evidence supports one obvious action
+   -> yes: fast path
+   -> no: branch mentally
+-> choose and bound one environment action
+-> execute once
+-> observe the actual result
+-> identify what changed
+-> return the observation and state change to the current owner
+```
+
+Action Selection improves one local interaction. It does not plan the whole task or simulate a long future trajectory.
+
+## Take The Fast Path When The Action Is Obvious
+
+Use the direct tool when current evidence supports one known, mechanical, covered, and directly verifiable interaction.
+
+The fast path is not the first plausible action. Use it only when choosing the target, hypothesis, observer, effect, and scope requires no unresolved material judgment.
+
+Typical fast-path interactions include:
+
+- reading a known file, symbol, range, or artifact;
+- applying an already selected exact edit;
+- running the exact focused check required by the current method;
+- formatting an accepted changed file;
+- inspecting a known diff or generated result.
+
+Do not generate alternatives for an obvious continuation.
+
+An action is not obvious merely because it is easy to execute. Choosing where to search, which hypothesis to test, what boundary to observe, or what effect to apply normally requires the branch path when several materially different choices remain.
+
+## Branch Mentally, Execute Once
+
+Use the branch path when:
+
+- several actions are plausible;
+- the relevant target, hypothesis, observer, or scope is unsettled;
+- the likely interaction is broad, noisy, destructive, expensive, or difficult to recover;
+- recent interactions have not materially changed the current question or accepted outcome.
+
+Before touching the environment:
+
+1. name the question or concrete effect the next interaction must resolve or produce;
+2. check whether active evidence already answers it;
+3. consider only a few materially different actions—not synonyms of the same search or observer;
+4. reject actions that repeat unchanged evidence, revisit an eliminated path, or gather information without a current question;
+5. prefer the action most directly connected to the question;
+6. among similarly direct actions, prefer one that distinguishes the leading alternatives;
+7. among similarly discriminating actions, prefer the narrowest interaction with proportionate output, side effects, context residue, and recovery cost;
+8. execute only the selected interaction and decide again from reality.
+
+Keep this comparison internal unless it exposes a user-owned decision. Do not produce candidate tables, assign numeric scores, simulate several environment results, or plan multiple interactions before the first observation.
+
+## Prefer Decision-Bearing Actions
+
+A **decision-bearing action** produces a result that changes what the current owner should believe or do whether it supports or contradicts the leading hypothesis.
+
+Among actions already covered by the current route, authority, and any active execution contract, prefer one that:
+
+- bears directly on the current question or accepted outcome;
+- distinguishes meaningful alternatives;
+- uses the narrowest sufficient observer or effect;
+- avoids unchanged evidence, eliminated paths, and equivalent prior interactions;
+- produces a clear next branch under both favorable and unfavorable results;
+- keeps expected observation volume, context residue, side effects, reversibility, and recovery cost proportionate.
+
+Do not calculate a numeric value. Use these properties to reject low-value branches and select one useful interaction.
+
+The objective is not maximal information. It is the smallest observation or effect capable of changing the decision.
+
+## Shape The Environment Action
+
+Match the action and tool to the required relationship:
+
+- when the entity, artifact, location, or range is known, use a focused operation;
+- when ownership, callers, dependencies, or structure are the question, use the most structured relationship query available;
+- when the target is literal, generated, or dynamically referenced, use bounded text or content search;
+- when behavior is the question, use the smallest direct test, runtime observer, or reproduction that exercises the required boundary;
+- when an exact covered effect has already been selected, use the narrowest direct mutation operation;
+- when the relevant entity is genuinely unknown, use one bounded broad discovery action, then narrow from its result instead of restarting breadth.
+
+These rules apply across repositories, filesystems, local processes, browsers, databases, APIs, and other environments. Use environment-specific guidance when available.
+
+Bound the directory, entity, pattern, range, test target, time window, result count, requested fields, affected state, or recovery scope when the tool supports it.
+
+Tool sophistication is not evidence quality. Choose the simplest available operation that can establish the required boundary.
+
+## Update From Reality
+
+After execution, identify:
+
+- what fact, hypothesis, path, effect, or task state changed;
+- what became stronger, weaker, eliminated, contradicted, or still unresolved;
+- whether the interaction answered the current question or produced the intended effect;
+- what next branch, if any, is now supported.
+
+New information is not automatically decision-relevant information.
+
+If the observation did not change the decision or distinguish alternatives, do not repeat it through synonyms, nearby files, a wider version of the same search, or another tool returning equivalent evidence. Reframe the question, choose a different observer class, or stop with the missing evidence.
+
+When two or more recent interactions have not materially changed the current question, advanced the covered effect, or supported a new branch, read [Trajectory Stalls](references/trajectory-stalls.md) before another interaction.
+
+Repeat the loop only while the same current owner, question, authority, and execution contract remain valid and each interaction either changes the decision surface or advances the exact covered effect.
+
+## Return To The Current Owner
+
+Return the observation and its material state change to the activity that requested it. Action Selection does not interpret another method’s final claim or return directly to a compute profile.
+
+When an active execution contract exists, stop when its return condition is met. Do not reinterpret or expand the contract to keep interacting.
+
+Return to [Workflow](../workflow/SKILL.md) when the result changes authority, accepted scope, current ownership, accepted direction, the required observing boundary, or stop conditions.
+
+Use [Diagnose Failure](../diagnose-failure/SKILL.md) when repeated failure remains unexplained rather than selecting another speculative interaction.
+
+Stop when:
+
+- one next action is sufficiently supported;
+- the requested effect was produced;
+- no covered interaction can reduce the important uncertainty;
+- the active execution contract requires return;
+- another activity now owns the problem.
+
+The objective is not fewer tool calls at any cost. It is fewer low-value interactions while preserving supported outcomes.