@hassangameryt/freeflow 0.6.0 → 0.7.1

package/skills/execute-work/SKILL.md

@@ -1,102 +1,141 @@
 ---
 name: execute-work
-description: Use when executing or resuming implementation, fixes, prototypes, documentation updates, repository maintenance, or other concrete changes.
+description: Use when carrying out or resuming requested or approved implementation, fixes, prototypes, documentation, configuration, repository maintenance, or other concrete work.
 ---
 
 # Execute Work
 
-Carry out concrete work through bounded actions and fresh evidence only when it was requested or approved and the effective mode permits its effects.
+Turn one accepted outcome into a supported concrete result.
 
-A Slice is the shared coherent outcome. Execute Work owns each **bounded action**—one implementation, experiment, correction, or observation—inside it. A Slice need not have durable task memory; when one does, Track Work records its Current Slice.
+Workflow establishes the authority envelope and current Slice. Execute Work coordinates bounded execution and in-Slice continuation. It does not redefine intent, own durable task memory, make user decisions, prove claims beyond available evidence, or authorize checkpoints and follow-on work.
 
-Read [Execute Work edges](references/execute-work-edges.md) when work resumes from prior state, crosses a Slice boundary, reaches a selected checkpoint, or reveals separately controlled follow-on work.
+A **bounded action** is one coherent execution or learning result with a checkable claim. It may include several reads, edits, commands, files, and focused checks. A tool call, file change, or execution-method change is not automatically another bounded action.
 
-## Follow The Execution Route
+Read [Execute Work Edges](references/execute-work-edges.md) when resuming uncertain prior work, changing the Slice boundary, reaching a selected checkpoint, or exposing separately controlled follow-on work.
 
-Use this as a directed map, not a fixed phase sequence:
+## Follow The Execution Loop
+
+Use this as a feedback loop, not a mandatory phase sequence:
 
 ```text
-[Requested or approved concrete work; effective mode permits its effects]
--> [Orient and establish the current slice]
--> [Take one bounded action]
--> [Test or observe]
--> [Verify what the evidence proves]
-   -> clear local defect -> correct -> test or observe again
-   -> unclear, repeated, or route-changing result -> Workflow
-   -> supported -> silent self-review -> freeze before acceptance or reuse
--> [Route]
-   -> more accepted work in this slice -> next bounded action
-   -> coherent boundary extension -> Workflow -> covered and recorded when needed -> next action
-   -> distinct result, authority, or evidence boundary -> Workflow
-   -> approved checkpoint due -> owning skill -> route again
-   -> supported exit -> report
+[Accepted concrete result]
+-> [Consume the current Slice and relevant live state]
+-> [Choose one bounded action and a check that can disagree]
+-> [Choose one primary execution route]
+-> [Execute and observe]
+-> [Determine what the evidence supports]
+   -> unsupported cause or repeated failure -> Diagnose Failure
+   -> user-owned choice or source conflict -> Decision Gate
+   -> supported -> Verify at the required boundary
+                -> self-review
+                -> accept or correct once
+-> [Continue inside the Slice or return the changed boundary to Workflow]
 ```
 
-Implementation beginning does not justify continuation. Continue only while authority, evidence, and the current slice remain coherent.
+Implementation beginning does not justify continuation. Continue only while the accepted result, authority, evidence boundary, and Slice remain coherent.
+
+## Enter From Established Direction
+
+Consume the understanding already established by the request, [Discuss](../discuss/SKILL.md), Workflow, and accepted source truth. Do not restart discovery or recreate task context merely because execution began.
+
+Before effects:
+
+- confirm the concrete result and relevant non-goals;
+- inspect the smallest live source set needed to avoid relying on stale context;
+- identify one bounded action;
+- name the claim its result must support;
+- identify a direct check or observation that can disagree;
+- confirm no selected checkpoint or separately controlled boundary is already due.
+
+When a Working Record exists, use [Track Work](../track-work/SKILL.md) for recovery, reconciliation, and write-ahead Current Slice state before relying on or changing it. Do not create durable memory for a short direct result merely because execution was selected.
+
+Return to [Workflow](../workflow/SKILL.md) when the intended result, authority, or current Slice is missing or materially inconsistent. Use [Decision Gate](../decision-gate/SKILL.md) when one known user-owned choice or source conflict blocks execution.
 
-## Orient Before Changing State
+## Bound The Action
 
-Establish:
+Choose the smallest coherent action that can produce a useful result and evidence.
 
-- intended result and the source that supports it;
-- current slice, accepted scope, and relevant live state;
-- the current authority envelope, due checkpoints, and separately controlled boundaries;
-- direct check or observation that can disagree with the result;
+A bounded action may be:
 
-Execute Work inherits the authority envelope established by Workflow; selecting this method does not create execution authority. A small self-contained change needs no Spec, Plan, or Working Record merely because execution was selected.
+- one accepted behavior implemented through a vertical test-first loop;
+- one behavior-preserving simplification with before-and-after evidence;
+- one coherent documentation, configuration, or repository change;
+- one reversible learning result with a discard, revise, or promotion condition;
+- one direct mechanical result whose complete effect is already clear.
 
-Inspect relevant code, tests, docs, policies, artifacts, repository state, and current external constraints before relying on memory. When sources materially conflict or the intended result is unsafe to infer, return the evidence to [Workflow](../workflow/SKILL.md) rather than choosing silently.
+Keep unrelated work and later outcomes outside it. Do not split an action merely because it touches several files or tools. Do not combine results that require different authority, evidence boundaries, or independently useful outcomes.
 
-When a Working Record exists, use [Track Work](../track-work/SKILL.md) for write-ahead slice state and later reconciliation. Announce the active slice once in a compact line when useful; do not announce every action or manufacture an identifier for a tiny task.
+Allow routine adaptation of local mechanics, ordering, and focused checks while the accepted result, permitted effects, and acceptance boundary remain unchanged. Return material changes to scope, behavior, evidence quality, persistence, or stop conditions to Workflow before acting.
 
-## Bound Each Action
+## Choose One Execution Route
 
-Choose the smallest coherent action that can produce the intended result or useful evidence:
+Use one primary execution route at a time:
 
-- keep unrelated and later work outside it;
-- choose reversible local details from repository conventions;
-- let an experiment fail safely and preserve its discard, revise, or promote condition;
-- keep every experiment and observation inside the authority envelope;
-- use only specialized methods and domain guidance that the concrete boundary needs.
+- execute directly when the effect is known, mechanical, and directly verifiable;
+- use [TDD](../tdd/SKILL.md) when accepted behavior should be guided by an observed failing check;
+- use [Simplify Code](../simplify-code/SKILL.md) when working behavior should become easier to understand or change without altering its contract;
+- use the required domain guidance when technology, risk, or repository conventions need a specialized method;
+- use [Diagnose Failure](../diagnose-failure/SKILL.md) before correction when the cause is unsupported or repeated attempts have failed.
 
-When several environment actions or observers could produce useful evidence, or the likely action is broad, use [Action Selection](../action-selection/SKILL.md) to choose and bound one interaction. Execute Work keeps ownership of the intended result and accepted effects; Action Selection returns the observation or bounded effect. Skip it when the next action is already known, mechanical, and directly verifiable.
+When specialized guidance is needed, read [Domain Skill Composition](../workflow/references/domain-skill-composition.md). Keep one Freeflow owner and return domain evidence to the current route.
 
-When an accepted behavior change, bug correction with a supported cause, consequential rule, or behavior-preserving refactor benefits from a failing check first, use [TDD](../tdd/SKILL.md) for that bounded action before changing production behavior.
+Before writing or changing code, read [Code Practices](references/code-practices.md).
 
-Before work changes the intended result, scope, permitted effects, evidence boundary, stop condition, or authority source, decide through Workflow whether it is an accepted extension or a new slice. When a Working Record exists, use Track Work to record an accepted extension before executing it. Do not let a series of “small” additions silently replace the original result.
+Action Selection controls environment interactions, not execution-method choice. When the next interaction is uncertain, broad, or likely to repeat without changing understanding, use [Action Selection](../action-selection/SKILL.md) to select and bound one useful interaction. When the next read, edit, or check is obvious, take its fast path directly.
 
-## Execute For The Required Boundary
+## Execute Without Drifting
 
-Match implementation and evidence to the work. Code may need behavior tests or runtime observations. Documentation, configuration, generated artifacts, and repository maintenance may need parsing, links, builds, diffs, structural checks, or installed-artifact evidence.
+Implement the bounded result through the selected route.
 
-Do not rewrite tests, checks, Specs, Plans, policies, or accepted behavior merely to make implementation pass. Determine whether the implementation, evidence, environment, or source is wrong before changing what defines success.
+Preserve accepted behavior, source truth, repository conventions, and relevant failure semantics. Do not rewrite tests, checks, Specs, Plans, policies, or established behavior merely to make implementation pass.
 
-Before writing or changing code, read [Code Practices](references/code-practices.md). Prefer clear ownership, names, and failure behavior. Comment only non-obvious rationale, constraints, invariants, or temporary behavior with a real exit condition.
+Handle an edge case only when accepted behavior, observed evidence, or material safety requires it and the expected result is settled. Return undefined observable behavior to Workflow rather than encoding a guess.
 
-Handle an edge case only when accepted behavior, observed evidence, or material safety requires it. If expected behavior is undefined and would change observable behavior or scope, return it to Workflow. When related patches keep adding states, flags, or caller coordination, stop and return the shared pressure rather than extending the patch stream.
+Let experiments fail safely. Keep disposable or diagnostic output outside production behavior until promotion is deliberately selected.
 
-## Close Each Evidence Iteration
+Stop the patch stream when related corrections keep adding caller coordination, public states, flags, retries, test-only seams, or recovery rules. Diagnose the shared cause before another patch. Use [Design for Depth](../design-for-depth/SKILL.md) only when direct evidence establishes structural ownership, interface, state, or failure-unit pressure.
 
-After every bounded action:
+Do not turn nearby cleanup, documentation, migration, deprecation, commit, push, integration, release, or launch into implied execution scope.
 
-1. run the focused tests or observations appropriate to its claim;
-2. use [Verify Work](../verify-work/SKILL.md) when the claim or observing boundary needs its fuller method;
-3. once initial evidence supports the result, use [Review Work](../review-work/SKILL.md) for silent self-review;
-4. correct clear local issues within existing authority and re-verify the affected boundary;
-5. confirm the final state has no unresolved material issue, freeze it, and only then accept, reuse, or report the result.
+## Accept Evidence At The Claim Boundary
 
-Self-review remains inside the bounded action rather than creating another action or review cycle. A failed or inconclusive check does not prove the design or source is wrong. Correct a clear local defect; use [Diagnose Failure](../diagnose-failure/SKILL.md) when the cause is unclear or failure repeats.
+Close the evidence iteration when the bounded action’s claim is ready to be accepted or used by dependent work—not after every edit or command.
 
-Further polish, advisory warnings, unrelated issues, and review findings without mutation authority are feedback to classify, not permission to keep editing.
+1. Run the focused checks or observations required by the selected method.
+2. Use [Verify Work](../verify-work/SKILL.md) when the claim or observing boundary needs explicit factual classification.
+3. Once fresh evidence supports the claim, use [Review Work](../review-work/SKILL.md) for silent self-review.
+4. Return one clear local defect to the producing route when existing authority covers correction.
+5. Re-run the affected evidence and repeat only the affected review lenses once.
+6. Use Diagnose Failure when the cause is unclear or correction repeats.
+7. Use Decision Gate when evidence exposes unsettled behavior or a user-owned choice.
 
-## Route Continuation Deliberately
+A green check does not prove behavior it did not exercise. Source inspection does not prove runtime behavior. Review judgment does not replace verification.
 
-Continue inside the current slice when the next bounded action is accepted, its intended result remains coherent, the combined boundary can still be verified as one unit, no stop condition applies, and no checkpoint is due.
+Further polish, advisory warnings, unrelated findings, and optional improvements are feedback to classify—not authority to keep editing.
 
-Before a distinct result begins, let Workflow establish the current slice outcome, then use Track Work when present to select the next authorized slice. A route through discussion, diagnosis, review, verification, or an approved checkpoint does not itself end or replace the current slice.
+## Continue Or Return
 
-A Plan preserves intended strategy, not progress. Return material changes to its order, mechanism, dependencies, slices, or checks to Workflow. Do not add public documentation, migration, deprecation, push, integration, release, launch, or another separately controlled action without its own authority.
+Continue inside the same Slice when:
+
+- the next bounded action serves the same accepted result;
+- its authority and evidence boundary remain covered;
+- the combined result can still be verified coherently;
+- no stop condition or selected checkpoint is due.
+
+A method change, verification run, self-review, correction, or pause does not create or complete a Slice by itself.
+
+When durable memory exists, use Track Work to preserve only material changes to context, authority, Slice boundaries, evidence, blockers, decisions, checkpoints, and the next useful action. Do not record every command, edit, or execution choice.
+
+Return to Workflow before beginning a distinct result, crossing an uncovered boundary, changing the accepted strategy materially, or performing a selected checkpoint or separately controlled follow-on action.
 
 ## Report The Supported State
 
-Report the accepted result, fresh verification evidence and limits, material route changes, current slice or artifact state, and unresolved or unverified work. A supported action is not automatically a completed slice, and a completed slice does not authorize the next one.
+Report proportionately:
+
+- the concrete result;
+- the strongest fresh evidence and what it does not prove;
+- material corrections or route changes;
+- the Current Slice or checkpoint state when relevant;
+- unresolved, deferred, or unverified work.
+
+A supported bounded action is not automatically a completed Slice. A completed Slice does not authorize a checkpoint, another Slice, push, integration, release, or launch.

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

@@ -1,6 +1,6 @@
 # Code Practices
 
-Read this before an Execute Work slice writes or changes code. Follow the repository's language, style, testing, and documentation conventions before generic advice.
+Read this before a bounded action writes or changes code. Follow the repository's language, style, testing, and documentation conventions before generic advice.
 
 ## Make Intent Legible
 
@@ -55,7 +55,7 @@ Before adding behavior for an edge case, ask:
 Then act proportionately:
 
 - **Required or observed, with defined behavior:** implement the smallest complete behavior and test the relevant boundary.
-- **Material but undefined:** stop and return the missing behavior decision to Workflow.
+- **Material but undefined:** stop and return the missing behavior decision to [Workflow](../../workflow/SKILL.md).
 - **Plausible but unsupported:** gather evidence; do not add speculative handling.
 - **Useful but optional:** report or defer it as separate work.
 - **Purely hypothetical:** leave it alone.
@@ -73,6 +73,6 @@ Each correction reveals another related state or flag
 
 Prefer an explicit invariant or clear failure over invented retry, fallback, recovery, or compatibility behavior. Handling an edge case creates a contract and future maintenance cost.
 
-## Stop When The Slice Is Supported
+## Stop When The Action Is Supported
 
-Once the accepted result is supported, comments are accurate, and no material self-review issue remains, stop. Possible polish, unrelated cleanup, and imagined resilience are not unfinished work. They require new evidence or another selected slice.
+Once the accepted result is supported, comments are accurate, and no material self-review issue remains, stop. Possible polish, unrelated cleanup, and imagined resilience are not unfinished work. They require new evidence or another accepted bounded action.

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

@@ -1,42 +1,62 @@
 # Execute Work Edges
 
-Read this after [Execute Work](../SKILL.md) when work resumes from prior state, crosses a Slice boundary, reaches a selected checkpoint, or reveals separately controlled follow-on work. Execute Work owns the normal action, evidence, method, and continuation loop; this reference covers exceptional transitions.
+Read this when execution resumes from uncertain prior state, changes the Slice boundary, reaches a selected checkpoint, or exposes separately controlled follow-on work.
+
+The main skill owns the normal bounded-action loop. This reference covers transitions that leave, resume, or constrain that loop.
 
 ## Resume Safely
 
-Reopen the source that established the work and inspect live state. When durable task memory exists, request the bounded `resume` view through [Track Work](../../track-work/SKILL.md), then retrieve exact entities only when the next decision needs them.
+Recover the source that established the accepted work and compare it with relevant live state.
+
+When durable memory exists, enter [Track Work](../../track-work/SKILL.md) and use its required recovery route before relying on or mutating the Working Record. Memory preserves context; it does not prove live state or recreate authority.
+
+Resume the same Slice only while its intended result, authority, evidence boundary, and stop condition remain coherent. Otherwise preserve supported work and return the changed boundary to [Workflow](../../workflow/SKILL.md).
+
+Do not restart discovery, repeat supported work, or infer progress from summaries, Plans, records, handoffs, staged files, or partial artifacts.
 
-Re-establish authority from the current conversation and still-valid approval. A summary, Plan, Handoff, Working Record, or another conversation branch preserves context but does not create current authority or prove progress.
+## Distinguish Adaptation From Boundary Change
 
-Preserve supported work and resume the same Slice only while its intended result, authority, evidence boundary, and stop condition remain coherent. Otherwise return the changed boundary to [Workflow](../../workflow/SKILL.md).
+Routine changes to local mechanics, implementation order, tools, and focused checks remain inside the current bounded action when they preserve:
 
-## Cross A Slice Boundary Deliberately
+- the accepted result;
+- permitted effects;
+- source truth;
+- the required observing boundary;
+- the stop condition.
 
-Before beginning a distinct result, independently useful evidence boundary, uncovered effect, changed strategy, or separately controlled action:
+Return to Workflow when new evidence changes behavior, scope, persistence, compatibility, public interfaces, risk, evidence quality, or another user-owned outcome.
 
-1. stop the current action stream;
-2. preserve the supported result and live evidence;
-3. return the boundary change to Workflow;
-4. reconcile the current Slice through Track Work when one exists;
-5. begin another Slice only after its outcome and authority are established.
+Keep an accepted extension in the current Slice only when its result remains coherent, explicit authority covers the added effects, and the combined boundary can still be verified as one unit. When a Working Record exists, Track Work records the extension before execution.
 
-A verification run, self-review, review report, method change, or pause does not create or close a Slice by itself.
+Use another Slice when the work has a distinct result, authority source, evidence boundary, independently useful outcome, or explicit abandonment of the original result.
 
 ## Route A Selected Checkpoint
 
-When an approved checkpoint becomes due, stop before dependent work, use its owner, and return the result to Workflow. If its condition no longer holds, return the deviation instead of forcing the checkpoint.
+A checkpoint is due only when Workflow, an approved Plan, repository policy, or explicit discussion selected it.
 
-A checkpoint result may support continuation, correction, another route, deferment, or stopping. It does not authorize the next lifecycle stage. Track Work preserves selected and resolved checkpoint state when durable memory exists.
+Stop before dependent work, use the checkpoint’s owner, and return its result to Workflow:
+
+- [Decision Gate](../../decision-gate/SKILL.md) for a selected user decision;
+- [Review Work](../../review-work/SKILL.md) for selected independent judgment;
+- [Commit Work](../../commit-work/SKILL.md) for an authorized local commit;
+- [Handoff](../../handoff/SKILL.md) for selected continuity transfer;
+- [Finish Branch](../../finish-branch/SKILL.md), [Release Work](../../release-work/SKILL.md), or [Launch Work](../../launch-work/SKILL.md) for their separately authorized boundaries.
+
+When durable memory exists, Track Work preserves the checkpoint’s selection, condition, result, and task effect.
+
+Do not create a checkpoint merely because an action or Slice ended. Do not force a stale checkpoint when its condition, evidence, or protected boundary no longer holds.
 
 ## Separate Follow-On Work
 
-Use the owning method only after Workflow confirms its boundary and authority:
+Useful follow-on work is not implied authority.
+
+Return it to Workflow before using:
 
-- [Commit Work](../../commit-work/SKILL.md) for an authorized local checkpoint or simple push;
-- [Migration Work](../../migration-work/SKILL.md) for accepted consumer, state, or traffic movement;
-- [Finish Branch](../../finish-branch/SKILL.md) for integration, preservation, discard, or cleanup;
-- [Release Work](../../release-work/SKILL.md) for versioned publication;
-- [Launch Work](../../launch-work/SKILL.md) for production exposure or recovery;
-- [Handoff](../../handoff/SKILL.md) for point-in-time continuation transfer.
+- Commit Work for an unselected commit or push;
+- [Migration Work](../../migration-work/SKILL.md) for consumer, state, or traffic movement;
+- Finish Branch for integration, preservation, discard, or branch cleanup;
+- Release Work for versioned publication;
+- Launch Work for production exposure, rollback, or recovery;
+- Handoff for point-in-time continuation transfer.
 
-A useful follow-on result is not implicit authority. Return to Workflow when its scope, evidence, destination, or stop condition is not already covered.
+Preserve the supported execution result before routing away. A follow-on owner does not retroactively change the completed action or Current Slice.