@hassangameryt/freeflow 0.7.1 → 0.7.2

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

@@ -8,7 +8,7 @@ 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";
+import { PIFLOW_HOST } from "../fixtures/pi-host.js";
 
 const execFileAsync = promisify(execFile);
 
@@ -51,12 +51,12 @@ function context(cwd, options = {}) {
   };
 }
 
-function loadExtension() {
+function loadExtension(host = PIFLOW_HOST, runtimeApi = {}) {
   const handlers = new Map();
   const commands = [];
   const tools = [];
   const pi = {
-    host: PIFLOW_HOST,
+    host,
     registerTool(tool) {
       tools.push(tool);
     },
@@ -77,6 +77,7 @@ function loadExtension() {
     },
     setActiveTools() {},
   };
+  Object.assign(pi, runtimeApi);
   freeflowExtension(pi);
   return { handlers, commands, pi };
 }
@@ -263,14 +264,22 @@ test("Cognitive Routing preset cancellation preserves the previous repository va
     cognitiveRouting: {
       enabled: true,
       profiles: {
-        standard: { provider: "test", model: "model-a", thinkingLevel: "low" },
-        reasoning: { provider: "test", model: "model-b", thinkingLevel: "high" },
+        coordinator: { provider: "test", model: "model-a", thinking: "low" },
+        executor: { provider: "test", model: "model-b", thinking: "high" },
       },
     },
   });
   const original = await readFile(join(cwd, ".freeflow/config.json"), "utf8");
   try {
-    const { commands } = loadExtension();
+    const { commands } = loadExtension(
+      {},
+      {
+        setModel() {
+          return true;
+        },
+        setThinkingLevel() {},
+      },
+    );
     const command = freeflowCommand(commands);
     const settings = context(cwd, { isIdle: () => true });
     settings.modelRegistry = cognitiveRoutingModelRegistry();
@@ -300,13 +309,21 @@ test("Cognitive Routing settings refresh after enabling the capability", async (
     cognitiveRouting: {
       enabled: false,
       profiles: {
-        standard: { provider: "test", model: "model-a", thinkingLevel: "low" },
-        reasoning: { provider: "test", model: "model-b", thinkingLevel: "high" },
+        coordinator: { provider: "test", model: "model-a", thinking: "low" },
+        executor: { provider: "test", model: "model-b", thinking: "high" },
       },
     },
   });
   try {
-    const { commands } = loadExtension();
+    const { commands } = loadExtension(
+      {},
+      {
+        setModel() {
+          return true;
+        },
+        setThinkingLevel() {},
+      },
+    );
     const command = freeflowCommand(commands);
     const settings = context(cwd, { isIdle: () => true });
     settings.modelRegistry = cognitiveRoutingModelRegistry();
@@ -322,13 +339,63 @@ test("Cognitive Routing settings refresh after enabling the capability", async (
       component.handleInput("\r");
       await component.waitForWrites();
       component.handleInput("\u001b");
-      assert.match(component.render(120).join("\n"), /Cognitive Routing\s+enabled \(5\) configured/);
+      assert.match(component.render(120).join("\n"), /Cognitive Routing\s+enabled \(4\) 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("Cognitive Routing settings can disable projection without disabling routing", async () => {
+  const cwd = await configuredRepo({
+    cognitiveRouting: {
+      enabled: true,
+      projection: true,
+      profiles: {
+        coordinator: { provider: "test", model: "model-a", thinking: "low" },
+        executor: { provider: "test", model: "model-b", thinking: "high" },
+      },
+    },
+  });
+  try {
+    const { commands } = loadExtension(
+      {},
+      {
+        setModel() {
+          return true;
+        },
+        setThinkingLevel() {},
+      },
+    );
+    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");
+      for (let index = 0; index < 3; index += 1) component.handleInput("\u001b[B");
+      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 repo", settings);
     const saved = JSON.parse(await readFile(join(cwd, ".freeflow/config.json"), "utf8"));
     assert.equal(saved.cognitiveRouting.enabled, true);
+    assert.equal(saved.cognitiveRouting.projection ?? false, false);
     assert.equal(settings.reloads.length, 1);
   } finally {
     await rm(cwd, { recursive: true, force: true });

package/plugin.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
   "name": "freeflow",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "description": "Feedback-based control system for coding agents.",
   "author": {
     "name": "Hassan Mohiddin"

package/runtime/prompts/cognitive-routing.md

@@ -1,10 +1,9 @@
 ## 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`.
+Cognitive Routing uses Coordinator and Executor in one agent/session to improve quality, continuity, responsiveness, and total cost together. Coordinator guides and assesses Executor's bounded work.
 
-- **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.
+Use the latest Runtime State for control, profile, and current responsibility. Under Manual or inactive routing, stop applying the automatic split and follow ordinary Workflow.
 
-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.
+Before relying on automatic routing, read the complete cognitive-routing skill if its body is absent. This bootstrap read is the only environment call in that response. If unavailable, stop and report the missing method. Reload it after context loss before applying remembered routing rules.
 
-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.
+When projection is on, Executor must project every completed skill and instructional-reference read, including this bootstrap read. Follow the skill for tool access, execution, evidence, handoffs, context cleaning, and recovery.

package/runtime/prompts/core.md

@@ -1,84 +1,90 @@
 # 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.
+Freeflow is a workflow layer for one active coding agent. It does not override user instructions, repository policy, host safety, or tool permissions, and it creates no authority. Core guidance and the separately editable Interaction Contract are delivered together whenever Freeflow is enabled.
 
-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.
+Use the latest Freeflow Runtime State and only the guidance, skills, and tools exposed for this request. State refreshes at session start, after context loss, or when displayed facts change; an unchanged snapshot may remain visible. Earlier snapshots are history.
 
 ## 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.
+- **Work agreement:** the user-established outcome, scope, and user-facing return condition. It may include figuring out the approach; it is not a mandatory artifact or another authority source.
+- **Passive observation:** inspecting existing sources or evidence without exercising target behavior or intentionally changing task state.
+- **Active evidence generation:** exercising behavior to produce evidence, including tests, reproductions, benchmarks, prototypes, instrumentation, and runtime probes.
+- **Mutation or delivery:** changing repository, durable task/session, or external state.
+- **Bounded activity:** coherent discussion, preservation, execution, evidence, or judgment ending in one assessable result.
+- **Current owner:** the one activity responsible for that result. Supporting methods, lenses, tools, references, and reviewers do not automatically take ownership.
+- **Slice:** one coherent outcome that may span several bounded activities. Track Work gives it durable identity when task memory is needed.
+- **Evidence boundary:** the strongest claim directly supported by the observing mechanism—not by intent, authority, or confidence.
+- **Self-review:** the producer silently checks an initially supported result for alignment, correctness, suitability, and unnecessary complexity before accepting or reusing it. Corrected work receives only the affected recheck.
+- **Independent review:** separately selected judgment from a context that did not produce the reviewed state. It reports without editing or authorizing correction.
+- **Checkpoint:** a deliberately selected boundary that dependent work must not cross unresolved. An activity ending or pausing does not create one automatically.
+- **Re-entry:** return only to the owner whose responsibility changed, preserving unaffected work, decisions, and evidence.
+- **Supported Exit:** an answer, wait, pause, handoff, deferment, controlled boundary, stop, or completion justified by current evidence and authority.
+
+## Load The Selected Method
+
+Before applying a selected skill, read its current body when its exact method is absent from context. Descriptions select methods; they do not replace them. Reuse still-visible guidance instead of rereading each turn.
+
+Read dependencies at their declared conditions, not the whole catalogue. Loading guidance neither changes ownership nor authorizes effects. Required reads still follow active capability bootstrap and routing rules.
 
 ## 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.
+After compaction, context-replacing summarization, clear, session resume/navigation, transfer into another context, or uncertain continuity, pause task work. Use only necessary recovery reads until state is coherent; recovery is not a bypass of authority, capabilities, or host permissions.
 
-Before continuing:
+- Require the latest Freeflow Runtime State; do not infer missing or contradictory state.
+- Reload relevant active capability methods before relying on them.
+- When a Working Record exists or may exist, load Track Work and read the complete `full` record. A summary or `resume` projection is not full recovery. Stop affected work if recovery is incomplete or unavailable.
+- Identify the current owner and reload its method if absent. Use Workflow when authority, ownership, or continuation is unclear.
+- Reconcile the agreement, current work, dependencies, evidence limits, partial effects, and stop conditions with current user direction and relevant live sources.
 
-- 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.
+Summaries and records may preserve evidence of prior approval; check that the approval still applies. They do not create authority, prove live state, or keep an absent method active. Current user direction, live source truth, and current Runtime State take precedence over conflicting memory. With intact context, use bounded record reads only when needed; another turn or ordinary pause is not context loss.
 
 ## 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.
+The **Interaction Lifecycle** runs from Entry through the Feedback Loop when needed to a Supported Exit. A later user turn or new evidence begins another lifecycle. One lifecycle may contain several bounded activities.
 
 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
+Orient or reconstruct state
+-> choose or retain the current owner
+-> establish the required result and a supported approach
+-> apply its method and gather or produce evidence
+-> determine what the evidence supports
 -> 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:
+Reuse settled understanding. For concrete work, resolve what is required and how to produce the next result before production changes; these need not be separate investigations or user turns. A learning action answers its bounded question, not an expanding production ambition.
+
+When the owner needs the environment, the **Environment Interaction Loop** is:
 
 ```text
 Need evidence or a covered effect
--> select and bound one environment action
--> choose the tool
+-> reuse adequate context or identify what is missing
+-> select and bound the action and tool
 -> execute once
--> observe
--> identify what changed
--> reconcile observation residency when available
+-> observe what changed
+-> apply active capability guidance where relevant
 -> 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.
+This inner loop may run zero or more times per activity. It does not change authority or ownership.
+
+## Evidence And Judgment
+
+Verification establishes what direct evidence proves at the observed boundary. Review judges whether work or an artifact is aligned, correct, suitable, and sufficiently evidenced; judgment does not replace verification. A passing check may leave a broader claim unsupported. Preserve missing, contradictory, and inconclusive evidence rather than converting it into success.
 
 ## 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.
+Use Workflow when authority, readiness, ownership, re-entry, checkpoints, continuity, or Supported Exit needs coordination. Continue covered work to the agreed return boundary; internal method returns do not end the user agreement.
+
+Before an uncovered effect or separately controlled action, explain its purpose, action, expected result, and stop condition; ask once and wait. Skills, artifacts, reviews, memory, and useful 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.
+Use Action Selection before an uncertain, broad, or repeated environment interaction. Seek the smallest sufficient observation or effect for the current question, bound its output, and return what changed to the owner. Use the fast path for an obvious covered mechanical action; do not manufacture alternatives or collect context after the question is settled.
 
 ## 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.
+Exit only when evidence and authority support it, applicable self-review and selected checkpoints are resolved, and required task memory and artifacts are accurate. Make material gaps, contradictions, deferrals, and user-owned decisions explicit. Report the outcome, evidence, limits, and current route.

package/runtime/prompts/interaction-contract.md

@@ -1,11 +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.
+Read the whole user turn and respond as a collaborative senior engineer. Respect user-owned goals and choices; judge claims from evidence rather than merely agreeing. Resolve available facts yourself, expose consequential tradeoffs, recommend when warranted, and state uncertainty or revise your position honestly.
 
-Questions, criticism, examples, hypotheses, and tentative ideas do not authorize action by themselves.
+Interpret requested intent, not sentence form. A question can request action. Questions, criticism, examples, hypotheses, and tentative ideas do not authorize action by themselves. Treat hypothetical or quoted instructions as discussion unless the user adopts them as a current request. Do not infer execution authority merely because discussion converged.
 
-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.
+For execution, establish the outcome, scope, and user-facing return condition. If the request already makes them clear, proceed without redundant confirmation. Otherwise ask only the missing material question and wait before the unsettled action. Use Workflow to coordinate covered execution; do not require the user to supply implementation mechanics.
 
-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.
+When a turn combines a question with requested action, answer the question before any action that depends on it. Proceed when that action remains clear, supported, and authorized. If the answer could change the user's choice, exposes a source conflict, or leaves action conditional, explain and wait. An unresolved question does not automatically suspend independent, clearly authorized work.
 
-Use Freeflow terminology in user-facing responses only when it materially improves clarity. Otherwise speak in ordinary engineering language.
+Ask before going beyond the agreement. Use ordinary language unless Freeflow terminology materially improves clarity.

package/skills/action-selection/SKILL.md

@@ -1,140 +1,100 @@
 ---
 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."
+description: "Use when choosing or bounding an environment interaction, especially when the needed context, target, observer, or scope is uncertain, output may be broad, or recent actions have not advanced the current question."
 ---
 
 # 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.
+Choose one covered environment interaction that advances the current question or result, observe what it actually changes, 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.
+An environment interaction is a bounded tool-mediated observation or effect. A current activity can need several interactions; a tool call is not a task phase, Slice, or reason to change ownership.
 
-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.
+Action Selection does not decide the user's outcome, work agreement, execution method, Slice, checkpoint, or Workflow route. It serves the owner responsible for those judgments and cannot accept the whole result.
 
-## Run One Interaction Loop
+## Identify The Immediate Need
 
-```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
-```
+Before touching the environment, identify what this interaction must answer or produce. Reuse evidence already available and current enough for that purpose.
 
-Action Selection improves one local interaction. It does not plan the whole task or simulate a long future trajectory.
+The need may be:
 
-## Take The Fast Path When The Action Is Obvious
+- understanding the required outcome or reported symptom;
+- establishing the mechanism, dependency, or approach;
+- applying an understood change;
+- observing whether a claim holds;
+- reconstructing missing continuation state.
 
-Use the direct tool when current evidence supports one known, mechanical, covered, and directly verifiable interaction.
+Use these purposes to focus the action, not to print phase labels or restart planning. Ask: what is the minimum sufficient context or effect for this next decision? Minimum means sufficient, not merely short.
 
-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.
+Do not collect information because it may be useful later. Do not confuse the existence of a source or reference with having its necessary contents available.
 
-Typical fast-path interactions include:
+## Take The Fast Path When The Action Is Known
 
-- 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.
+Use the direct tool when the target, purpose, scope, and observing boundary are already supported and the action is covered, mechanical, and directly verifiable.
 
-Do not generate alternatives for an obvious continuation.
+Examples include reading a known function or range, applying an exact selected edit, running an already-chosen focused check, or inspecting its resulting diff.
 
-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.
+Do not manufacture alternative tools or repeat the action-selection method for an obvious continuation. A command being easy to run does not make its target or hypothesis well chosen.
 
-## Branch Mentally, Execute Once
+## Compare Only Meaningful Alternatives
 
-Use the branch path when:
+When the target, observer, or scope is uncertain, likely output is broad, the action is destructive, expensive, or difficult to recover, or recent work has stalled:
 
-- 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.
+1. Identify the fact or effect the current owner needs.
+2. Check whether existing evidence already supplies it.
+3. Consider only a few materially different ways to obtain it.
+4. Reject unchanged rereads, equivalent searches, eliminated approaches, and information without a current use.
+5. Prefer the most direct action that distinguishes the plausible answers.
+6. Among equally useful actions, prefer proportionate output, side effects, context residue, and recovery cost.
+7. Execute the selected action once; choose the next interaction from its actual result.
 
-Before touching the environment:
+Keep this comparison internal unless a user-owned choice is exposed. Do not emit candidate tables, numeric scores, simulated results, or a speculative sequence of tool calls.
 
-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.
+A good observation can change the owner's belief or next action whether it supports or contradicts the leading explanation. An exact mutation can advance a settled result without testing a new hypothesis.
 
-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.
+## Bound The Tool And Its Output
 
-## Prefer Decision-Bearing Actions
+Use the simplest operation that can establish the required relationship:
 
-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.
+- known file, symbol, artifact, or range -> focused read or operation;
+- ownership, caller, or dependency question -> structured relationship query where available;
+- literal or generated reference -> bounded content search;
+- behavioral claim -> the owner's selected test, observer, or reproduction;
+- understood effect -> narrow direct mutation;
+- unknown location -> bounded discovery, then narrow from its result.
 
-Among actions already covered by the current route, authority, and any active execution contract, prefer one that:
+Choose scope before execution: directory, source kind, pattern, range, test target, time window, result count, fields, affected state, or recovery scope. Exclude unrelated history, generated output, and dependencies unless the current question needs them.
 
-- 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.
+Use a location or count query before requesting all matching bodies when volume is uncertain. Prefer bounded output with an accessible full result. Truncation or a sampled result must remain explicit; it is not proof that omitted matches are irrelevant or that a search was exhaustive.
 
-Do not calculate a numeric value. Use these properties to reject low-value branches and select one useful interaction.
+Context cost includes instructions, results, repeated material, and the capacity still needed for implementation, checking, correction, and continuation. Use host-supplied usage when available; do not invent token measurements or treat the provider maximum as a promise that a unit will fit.
 
-The objective is not maximal information. It is the smallest observation or effect capable of changing the decision.
+The owner selects the work horizon. Return unexpectedly large context needs to it instead of reading the entire dependency tree or silently shrinking acceptance.
 
-## Shape The Environment Action
+## Observe Before Continuing
 
-Match the action and tool to the required relationship:
+After the interaction, determine:
 
-- 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.
+- what actually ran or was returned;
+- what changed in evidence, hypotheses, implementation, or task state;
+- whether the intended question was answered or effect produced;
+- which uncertainty, partial effect, or contradictory observation remains.
 
-These rules apply across repositories, filesystems, local processes, browsers, databases, APIs, and other environments. Use environment-specific guidance when available.
+New content is not automatically useful evidence. A successful read is not understanding; a successful write is not correctness; a passing tool result is not proof of the wider claim. Return evidence to its owner for interpretation at the required boundary.
 
-Bound the directory, entity, pattern, range, test target, time window, result count, requested fields, affected state, or recovery scope when the tool supports it.
+When a read settles the question, stop that investigation. Ordinary local continuation may be obvious; an invalidated implementation premise needs reassessment before dependent effects.
 
-Tool sophistication is not evidence quality. Choose the simplest available operation that can establish the required boundary.
+If the result did not advance the question, do not repeat it using synonyms, nearby files, a wider equivalent search, or another tool. Change the question or observer, or report the missing evidence.
 
-## Update From Reality
+When two or more recent interactions have not materially changed understanding, advanced the covered effect, or supported a new branch, read [Trajectory Stalls](references/trajectory-stalls.md) before another interaction.
 
-After execution, identify:
+## Return Without Expanding The Work
 
-- 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.
+Return the observation and material state change to the same current owner. Action Selection does not transfer compute profiles, accept an implementation, or create authority.
 
-New information is not automatically decision-relevant information.
+When an experiment reveals a new prerequisite, report what it blocks: the current observer, chosen approach, or required outcome. Do not convert a blocked tool or prototype into permission to build a subsystem.
 
-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.
+Use [Diagnose Failure](../diagnose-failure/SKILL.md) for unexplained repeated failures. Return changed authority, scope, ownership, direction, evidence boundary, or stop conditions to [Workflow](../workflow/SKILL.md).
 
-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.
+Stop when the immediate need is satisfied, the active contract requires return, no useful covered interaction remains, or another activity must settle the next choice. Reuse adequate evidence instead of generating new calls to justify completion.
 
-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.
+The goal is fewer low-value interactions while preserving sufficient evidence and the agreed outcome—not fewer calls at any cost.