@hassangameryt/freeflow 0.6.0 → 0.7.1

package/skills/action-selection/SKILL.md

@@ -1,91 +1,140 @@
 ---
 name: "action-selection"
-description: "Use when selecting, bounding, or learning from an environment interaction, especially when several tool actions are plausible, expected output may be broad, or recent interactions have not materially changed the current understanding."
+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
 
-Control one environment interaction inside the active Workflow owner. Select and bound one action, learn from its actual result, and return the changed evidence to that owner.
+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.
 
-Action Selection does not choose the task owner, widen authority, decide accepted behavior, or replace implementation, diagnosis, verification, review, or other specialized methods.
+An **environment interaction** is one bounded tool-mediated observation or effect and the result it returns. A bounded activity may contain several environment interactions.
 
-## Run The Environment Interaction Loop
+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
--> choose the fast path or branch path
--> select and bound one action
+-> 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 to the owning activity
+-> return the observation and state change to the current owner
 ```
 
-### Use The Fast Path
+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.
 
-When current evidence supports one known, mechanical, covered, and directly verifiable action, use the direct tool and execute it.
+## Branch Mentally, Execute Once
 
-Do not generate alternatives before a focused read, accepted edit, exact check, formatting step, or other obvious continuation.
+Use the branch path when:
 
-### Use The Branch Path
+- 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.
 
-When several actions are plausible, the likely action is broad, or recent interactions have not changed the current understanding:
+Before touching the environment:
 
-1. name the question or outcome the next interaction must resolve;
-2. check whether active evidence already resolves it;
-3. consider only the few materially different actions;
-4. choose the action most likely to change the current decision with proportionate interaction, observation, side-effect, and recovery cost;
-5. execute one action and decide again from reality.
+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 the comparison internal unless it exposes a user-owned decision. Do not produce candidate tables, simulate a long future trajectory, or plan several environment steps before the first result arrives.
+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
 
-Among actions already covered by the current route and authority, prefer one that:
+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 the leading alternatives;
+- distinguishes meaningful alternatives;
 - uses the narrowest sufficient observer or effect;
-- avoids repeating unchanged evidence or an eliminated path;
-- produces a clear next branch whether the result supports or contradicts the current hypothesis;
-- keeps output, side effects, reversibility, and recovery cost proportionate.
+- 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.
 
-Do not calculate a numeric score. 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 Tool Action
+## Shape The Environment Action
 
-Match the tool and scope to the evidence or effect required:
+Match the action and tool to the required relationship:
 
-- use a focused source operation when the file, symbol, range, or artifact is known;
-- use semantic or structural navigation when ownership or relationships are the question;
-- use bounded text search when structural evidence is unavailable or the target is literal or dynamic;
-- use a targeted test or runtime observer when behavior is the question;
-- use a direct mutation tool only after the owning activity has selected the exact effect;
-- use broad search when the relevant source is genuinely unknown, then narrow from its result instead of restarting breadth.
+- 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.
 
-Bound the directory, symbol, pattern, range, test target, time window, result count, or requested fields when the tool supports it.
+These rules apply across repositories, filesystems, local processes, browsers, databases, APIs, and other environments. Use environment-specific guidance when available.
 
-Tool sophistication is not evidence quality. Choose the simplest available tool that can establish 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.
 
-## Update From The Observation
+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, or task state changed;
+- what fact, hypothesis, path, effect, or task state changed;
 - what became stronger, weaker, eliminated, contradicted, or still unresolved;
-- whether the result answered the current question;
-- what single next action, if any, is now supported.
+- 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
 
-If the observation did not change the decision or distinguish alternatives, do not repeat it through synonyms, nearby files, or another tool returning equivalent evidence. Reframe the question, choose a different kind of observer, or stop with the missing evidence.
+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.
 
-Repeat the loop only while the same owning activity and question remain valid and each observation changes the decision surface.
+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 The Owner
+Return to [Workflow](../workflow/SKILL.md) when the result changes authority, accepted scope, current ownership, accepted direction, the required observing boundary, or stop conditions.
 
-Return the observation and its state change to the activity that requested it.
+Use [Diagnose Failure](../diagnose-failure/SKILL.md) when repeated failure remains unexplained rather than selecting another speculative interaction.
 
-Return to Workflow when the result changes authority, scope, ownership, accepted direction, evidence boundary, or stop conditions. Return repeated unexplained failure to diagnosis rather than selecting another speculative action.
+Stop when:
 
-Stop when one next action is sufficiently supported, no covered interaction can reduce the important uncertainty, or another activity now owns the problem.
+- 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.

package/skills/action-selection/references/trajectory-stalls.md

@@ -0,0 +1,71 @@
+# Trajectory Stalls
+
+Read this when two or more recent environment interactions have not materially changed the current question, advanced the covered effect, or supported a new branch.
+
+A stall is evidence that the current interaction policy is no longer producing useful progress. It does not prove that the task is difficult, the design is wrong, or another model is required.
+
+## Recognize A Stall
+
+Common stall patterns include:
+
+- repeating searches with synonymous terms;
+- rereading unchanged sources without a new question;
+- rerunning the same check against unchanged state;
+- widening search breadth without narrowing the hypothesis;
+- collecting new output that does not change any belief or decision;
+- revisiting a path already eliminated by supported evidence;
+- changing hypotheses without a new observation;
+- alternating edits, failures, and reversions without a supported cause;
+- following each newly mentioned symbol or file away from the accepted outcome;
+- continuing because interaction began rather than because evidence supports another step.
+
+The following are not automatically stalls:
+
+- several distinct mechanical interactions required by one exact covered effect;
+- rerunning evidence after relevant state changed;
+- a long-running operation that is still producing the selected result;
+- checking a broader boundary after a focused result when that boundary was already required;
+- returning through several files along one supported call or dependency path.
+
+Judge progress by changed understanding, produced effects, or a newly supported branch—not raw action count.
+
+## Stop Before Another Similar Interaction
+
+Before another environment action:
+
+1. restate the unresolved question or exact covered effect;
+2. identify what the recent interactions established;
+3. identify which paths or hypotheses they eliminated;
+4. state why the interactions failed to change the decision;
+5. determine whether another observer class could discriminate where the previous one could not.
+
+Different observer classes may include:
+
+- structural navigation instead of text search;
+- caller or dependency tracing instead of concept search;
+- runtime behavior instead of source inspection;
+- source inspection instead of another runtime rerun;
+- exact artifact comparison instead of summary output;
+- a minimized reproduction instead of another speculative edit.
+
+Changing syntax, keywords, directories, or tools without changing the evidence relationship is not a different observer class.
+
+## Recover With One Discriminating Action
+
+When a different covered observer can answer the unresolved question:
+
+1. name what result would support or contradict the leading path;
+2. bound one interaction;
+3. execute it once;
+4. return its observation to the current owner.
+
+Do not compensate for a stall by generating a long plan, exploring every remaining path, or broadening the task.
+
+When no covered interaction can discriminate:
+
+- return the smallest missing evidence to the current owner;
+- return a changed authority, scope, ownership, direction, or required observing boundary to [Workflow](../../workflow/SKILL.md);
+- use [Diagnose Failure](../../diagnose-failure/SKILL.md) when repeated failure lacks a supported cause;
+- stop when the active execution contract requires return.
+
+A stall recovery succeeds when the decision surface changes or the absence of a safe useful interaction becomes explicit. It does not require another tool call.

package/skills/bypass/SKILL.md

@@ -1,83 +1,153 @@
 ---
 name: bypass
-description: Use when the user explicitly asks to skip or reduce workflow steps for the next action or current task.
+description: "Use when the user explicitly asks to skip or reduce optional workflow pressure for the next authorized activity or the current task."
 ---
 
 # Bypass
 
-Skip optional ceremony, not authority, judgment, safety, or evidence.
+Reduce explicitly selected optional workflow pressure without changing authority, accepted intent, the current owner, execution method, evidence semantics, selected checkpoints, mode, active capability protocols, or host controls.
 
-Bypass changes the workflow method within an already accepted action. It does not authorize work, expand scope, switch mode, resolve a user-owned decision, override source truth, or create host permissions.
+Bypass is a user-controlled pressure modifier. It does not authorize the underlying work and does not perform that work itself.
 
-## Establish The Boundary
+**Optional pressure** is a workflow step whose removal does not weaken accepted intent, material risk control, required evidence, a selected checkpoint, or safe continuation.
 
-Before using bypass, identify:
+## Interpret The Request Narrowly
 
-- the accepted action it applies to;
-- the named optional step, or whether the user selected `next` or `task` scope;
-- the effective mode;
-- the evidence and checkpoints that still govern the action.
+Use Bypass only when the user explicitly asks to skip or reduce workflow pressure. Do not infer bypass from urgency, frustration, brevity, “just do it,” or a preference for concise responses.
 
-A bare `/bypass` means `/bypass next`. If no accepted action exists, return to [Workflow](../workflow/SKILL.md); do not treat bypass itself as implementation authorization.
+Establish:
 
-Bypass never changes mode. In `conversation`, remain read-only and use [Mode Contract](../mode-contract/SKILL.md) before mutation. In `workflow` or `strict-workflow`, keep the active mode's decision and evidence pressure.
+- the already-authorized bounded activity;
+- the specific pressure the user wants removed;
+- whether the requested scope is `next` or `task`;
+- the authority, evidence, checkpoints, and stop conditions that remain;
+- when the bypass expires.
+
+A bare `/bypass` means `/bypass next`.
+
+If the same user turn both authorizes an activity and explicitly requests reduced pressure, interpret the whole turn through [Workflow](../workflow/SKILL.md). Bypass may modify that authorized activity; it does not supply its authority.
+
+If no authorized activity exists, return to Workflow and wait. Do not treat bypass as permission to implement, inspect actively, mutate, deliver, commit, or continue.
 
 ## Skip Only Optional Pressure
 
-A bypass may remove a step that does not protect accepted intent, material risk, required evidence, or a selected checkpoint, such as:
+A valid bypass may remove:
 
-- an unnecessary Spec or Plan;
-- extended questioning whose answer would not change the action;
+- an unnecessary Spec, Plan, or Working Record;
+- extended questioning whose answer would not change the accepted activity;
 - an artifact created only for ceremony;
-- an optional checkpoint or extra review with no remaining risk purpose.
+- duplicate explanation or status reporting;
+- a proposed but unselected review or checkpoint with no remaining risk purpose;
+- another optional step whose removal does not weaken the supported outcome.
 
-Do not infer that a named artifact or review is optional. Inspect why it exists first.
+Do not infer that a named artifact, review, check, or checkpoint is optional. Inspect what it protects before removing it.
+
+Freeflow should already avoid unnecessary ceremony. Bypass is an explicit user override when optional pressure was proposed or recommended but was not selected as a required boundary, or would otherwise remain in the route.
 
 ## Preserve Non-Bypassable Boundaries
 
-A generic or scoped bypass does not remove:
+Bypass does not remove or override:
+
+- the user’s authority over product behavior, scope, priorities, public interfaces, compatibility, permissions, security, privacy, billing, data loss, migration direction, deployment, or another hard-to-reverse outcome;
+- conflicts among the request, code, tests, docs, policies, requirements, accepted behavior, or another source of truth;
+- the accepted authority envelope or separately controlled effects;
+- host safety, sandbox, permission, approval, or tool controls;
+- mode boundaries or active capability protocols;
+- the distinction between available evidence and supported claims;
+- required self-review before accepting or reusing a supported result;
+- an accepted Spec, Plan, selected checkpoint, required artifact review, or selected independent review;
+- a stop condition, blocker, or evidence that invalidates the current route.
+
+Material risk still requires the decisions and evidence that address it. A domain label alone does not require ceremony, but bypass cannot erase an observed risk.
+
+Bypass cannot allow an active compute profile to act outside its execution protocol. Use the capability’s own user controls when the user wants to change manual or automatic control, profile behavior, or another capability setting.
+
+## Respect Declined Evidence Without Inventing Support
+
+A user may explicitly decline a test, build, runtime probe, review, or other evidence generation. Respect that instruction unless a higher-priority repository, host, or safety requirement prevents it.
+
+Declining evidence does not make the corresponding claim supported.
+
+When evidence is declined:
+
+- perform only the remaining authorized work that can continue safely;
+- leave the affected claim explicitly unverified;
+- do not accept or reuse the result beyond the remaining evidence boundary;
+- do not cross a checkpoint or dependent boundary that requires the missing evidence;
+- return to Workflow when the expected exit, checkpoint, or safe continuation must change.
 
-- the user's authority over product behavior, scope, public interfaces, compatibility, permissions, security, privacy, billing, data loss, migrations, deployment, or another hard-to-reverse outcome;
-- a conflict with code, tests, docs, policies, requirements, accepted behavior, or another source of truth;
-- host safety, sandbox, permission, or approval controls;
-- proportionate verification and required self-review for every bounded activity before its result is accepted, reused, or claimed complete;
-- an accepted Spec, Plan, selected checkpoint, required artifact review, selected independent review, or other accepted completion boundary;
-- a stop condition or evidence that invalidates the current route.
+A request to skip evidence generation changes what may be claimed. It does not change what the available evidence proves.
 
-Material risk still needs the decisions and evidence that address that risk. A domain label alone does not require ceremony, but bypass cannot erase an observed risk.
+## Route Changes Are Not Bypass
 
-If the user wants to change an accepted requirement, evidence boundary, or selected review, treat that as a route change rather than bypass. Use [Decision Gate](../decision-gate/SKILL.md) when one user-owned choice or source conflict blocks progress; use Workflow when the route itself must change.
+Treat the request as a Workflow route change when the user wants to:
+
+- change accepted behavior, scope, effects, or stop conditions;
+- weaken or replace an accepted evidence requirement;
+- cancel or replace a selected checkpoint;
+- revise an accepted Spec or Plan;
+- change mode or an active capability protocol;
+- continue despite contradictory evidence or a source conflict.
+
+An explicit user instruction may authorize the changed route, but Workflow must reconcile its consequences before dependent work continues.
+
+Use [Decision Gate](../decision-gate/SKILL.md) only when one user-owned choice or source conflict remains unresolved.
 
 ## Apply The Selected Scope
 
 ### Next
 
-`/bypass next` skips one identified optional step for the current accepted action. Re-check the route immediately after skipping it.
+`/bypass next` removes one identified optional pressure from the current authorized activity.
 
-If that step was the only remaining optional pressure, complete the bounded action and verify it. The bypass is then spent. It also expires if the action changes, another gate appears, or the route stops.
+The bypass is spent when:
+
+- the selected pressure is skipped;
+- the activity changes;
+- another gate or stop condition appears;
+- the route ends.
+
+Re-check the route immediately after applying it. Do not carry the bypass into another activity by implication.
 
 ### Task
 
-`/bypass task` reduces optional workflow pressure for the current accepted task. The task is the accepted request or active Working Record scope—not the repository, session, or future related work. If that boundary is unclear, ask before applying task scope.
+`/bypass task` reduces identified optional pressure for the current accepted task.
+
+The task is the accepted request or active Working Record scope—not the repository, session, branch, or future related work.
 
-The task scope ends at completion, abandonment, material scope change, or explicit withdrawal. Reassess each new risk, conflict, checkpoint, and completion claim inside that scope.
+Name the pressure being reduced when possible. Do not interpret task scope as “ignore all workflow for this task.”
 
-When an existing Working Record is already authorized for maintenance and task-scoped bypass must survive context loss, record its exact source, scope, and expiry through [Track Work](../track-work/SKILL.md). The record preserves the instruction; it does not broaden it. Without durable task memory, do not claim bypass survives context loss.
+Task scope ends when:
 
-Never convert either scope into a permanent, repository-wide, or cross-task bypass.
+- the task completes or is abandoned;
+- its accepted outcome changes materially;
+- the user withdraws or replaces the bypass;
+- a new task begins.
 
-## Act Or Stop
+Reassess new risks, conflicts, evidence requirements, checkpoints, and separately controlled effects inside the task. Task scope does not make them optional.
+
+When an existing Working Record is already authorized for maintenance and the task-scoped bypass must survive context loss, use [Track Work](../track-work/SKILL.md) to preserve its source, exact pressure, scope, and expiry.
+
+The record preserves the user instruction; it does not broaden it. Without durable task memory, do not claim task-scoped bypass survives context loss.
+
+Never convert `next` or `task` scope into permanent, repository-wide, session-wide, or cross-task behavior.
+
+## Return The Modified Route
 
 When the bypass is valid:
 
-1. skip only the selected optional pressure;
-2. perform only the separately authorized bounded action;
-3. gather the same proportionate evidence the outcome requires;
-4. silently self-review the supported result before accepting, reusing, or reporting it;
-5. report what was skipped, the result, and whether the bypass is spent or still task-scoped.
+1. identify the optional pressure being removed;
+2. apply only the selected scope;
+3. return the reduced-pressure route to the unchanged current owner;
+4. let that owner perform the separately authorized activity;
+5. preserve the same evidence honesty, self-review, and stop conditions;
+6. report what was skipped only when it materially clarifies the result or remaining scope.
+
+Do not narrate internal bypass state on every turn. Speak in ordinary engineering language unless the scope or expiry matters to the user.
 
 When a boundary remains:
 
 1. do not perform the blocked action;
-2. name the boundary bypass cannot remove;
-3. route to the owning mode, decision, discussion, or workflow step.
+2. state the boundary the bypass cannot remove;
+3. return to Workflow, Decision Gate, or the relevant current owner.
+
+Bypass ends when the selected optional pressure has been removed, its scope expires, or a non-bypassable boundary requires another route.