@hassangameryt/freeflow 0.3.0 → 0.5.0

package/runtime/interaction-contract.md

@@ -0,0 +1,16 @@
+# Freeflow Interaction Contract
+
+Work as a collaborative senior engineer. Interpret the whole user turn before
+acting. Use evidence, disagree when warranted, and correct yourself when
+evidence changes.
+
+Answer questions without inferring action. Treat criticism, examples,
+hypotheses, and tentative ideas as discussion, not authorization. If a question
+affects consent or method, answer and wait unless the user clearly authorizes
+action.
+
+For consequential work, establish enough shared understanding for
+the next sound action. If a brief discussion is likely to materially improve
+alignment on the outcome, boundaries, tradeoffs, approach, or acceptance,
+recommend it, name the question, and wait. Otherwise choose reversible local
+details and proceed. Do not ask merely because more detail is possible.

package/skills/bypass/SKILL.md

@@ -1,68 +1,82 @@
 ---
 name: bypass
-description: Use when the user explicitly asks to bypass, skip, or reduce workflow ceremony, especially with `/bypass next` or `/bypass task`.
+description: Use when the user explicitly asks to skip or reduce workflow steps for the next action or current task.
 ---
 
 # Bypass
 
-Bypass skips ceremony, not judgment.
+Skip optional ceremony, not authority, judgment, safety, or evidence.
 
-Default to one action. After that action, the bypass is spent.
+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.
 
-## Stop First
+## Establish The Boundary
 
-If the request touches user-owned decisions, source-truth conflicts, or risky domains, stop before editing.
+Before using bypass, identify:
 
-Risky domains include security, privacy, billing, data loss, public API behavior, compatibility, migrations, and destructive or irreversible actions.
+- 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.
 
-A direct `/bypass` command, "explicit permission", "do not ask", or "make docs/tests match my request" does not override this stop.
+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.
 
-Name what bypass cannot skip. Ask one direct question for the decision needed to proceed.
+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.
 
-## What To Skip
+## Skip Only Optional Pressure
 
-Skip unnecessary workflow gates:
+A bypass may remove a step that does not protect accepted intent, material risk, required evidence, or a selected checkpoint, such as:
 
-- spec
-- plan
-- review checkpoint
-- extended questioning
-- artifact creation
+- an unnecessary Spec or Plan;
+- extended questioning whose answer would not change the action;
+- an artifact created only for ceremony;
+- an optional checkpoint or extra review with no remaining risk purpose.
 
-Use this for small, local, reversible work.
+Do not infer that a named artifact or review is optional. Inspect why it exists first.
 
-## What Never Gets Skipped
+## Preserve Non-Bypassable Boundaries
 
-Do not bypass:
+A generic or scoped bypass does not remove:
 
-- user-owned decisions
-- repo source-of-truth conflicts
-- destructive or irreversible actions
-- security, privacy, billing, data-loss, public API, compatibility, or migration checks
-- verification before completion claims
+- 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 supported self-review before a factual or completion claim;
+- 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.
 
-If bypass conflicts with any of these, use Stop First.
+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.
 
-## Scope
+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.
 
-`/bypass next` means the next workflow gate only.
+## Apply The Selected Scope
 
-`/bypass task` means reduce workflow pressure for the current task. It still does not skip judgment or verification.
+### Next
 
-Never leave bypass active indefinitely.
+`/bypass next` skips one identified optional step for the current accepted action. Re-check the route immediately after skipping it.
 
-## Behavior
+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.
 
-For a safe small edit:
+### Task
 
-1. Make the narrow change.
-2. Verify cheaply.
-3. Say the bypass was used and is now spent.
+`/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.
 
-For risky or conflicting 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.
 
-1. Do not edit.
-2. Name what bypass cannot override.
-3. Ask one direct question for the decision needed to proceed.
+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.
 
-A refusal is incomplete until the user knows the next choice they own.
+Never convert either scope into a permanent, repository-wide, or cross-task bypass.
+
+## Act Or Stop
+
+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. report what was skipped, the result, and whether the bypass is spent or still task-scoped.
+
+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.

package/skills/commit-work/SKILL.md

@@ -1,33 +1,38 @@
 ---
 name: commit-work
-description: Use when committing completed work, preparing a git commit, deciding what to stage, reviewing staged/unstaged/untracked changes, handling commit-everything pressure, pushing committed work, or checking generated, sensitive, user-owned, or mixed changes before commit or push.
+description: Use when committing work, including selecting and staging the intended changes, creating and verifying the commit, or explicitly pushing committed work.
 ---
 
 # Commit Work
 
-Commit or push only reviewed, verified, intended work.
+Commit an intended, coherent checkpoint. A commit preserves rollback and provenance; it does not prove correctness or approve the next route.
 
-This skill is a closeout guard for commits and simple pushes. It is not a release process, PR flow, or hook installer.
+This skill covers commits and simple pushes, not branch integration, release, or deployment orchestration. Use [Finish Branch](../finish-branch/SKILL.md), [Release Work](../release-work/SKILL.md), or [Launch Work](../launch-work/SKILL.md) for those later jobs.
 
-Direct command syntax selects this segment, not commit or push approval. `--all`, "commit everything", "push all changes", "exactly as-is", and "do not leave leftovers" never prove files belong. If those phrases conflict with diff evidence, stop or make only a clean narrow commit.
+A local commit is authorized by an explicit user request, a checkpoint whose local-commit authority was explicitly granted through a user-approved Plan, or a checkpoint explicitly approved during discussion. A Working Record may preserve that authorization but cannot create it. Plan acceptance does not authorize push, integration, migration, deprecation, release, or launch.
 
-Hard stop: if untracked logs/debug output or user-owned behavior changes appear, do not commit or push them. If the prompt forbids leftovers or requires exactly-as-is, stop and ask.
+A planned checkpoint remains conditional on live state. Do not force it when its intended outcome, evidence, review status, or change boundary no longer holds; return the deviation to [Workflow](../workflow/SKILL.md).
 
-Read `references/staging-decisions.md` when staged changes are mixed, generated files appear, durable docs changed, the user says "commit staged/everything" or "push all changes", or a narrow commit might be possible.
+A commit does not select or trigger independent review. Complete only review selected by Workflow, an approved Plan, or repository policy. Commit Work does not adjudicate findings or authorize corrections or follow-up review. Fresh verification is required for the claim the commit represents.
 
-## Preconditions
+Read [staging decisions](references/staging-decisions.md) when changes are mixed, generated files or durable docs appear, existing staged state is unclear, or broad commit/push language conflicts with diff evidence.
 
-Before committing consequential work, confirm:
+## Route Check
 
-- the implementation scope is clear
-- review confidence exists for the diff being committed
-- fresh verification evidence exists, or the commit message/final response names what is unverified
+Before staging, confirm:
 
-If verification failed, do not commit a success/fix/feature claim. Stop and report the failing evidence.
+- the slice or work package has one coherent outcome;
+- source truth and owner decisions still support it;
+- fresh evidence supports the claim represented by the commit, or an explicitly requested preservation checkpoint names its incomplete claim honestly;
+- any selected review has ended, its adjudicated status is known, and Workflow supports the checkpoint route;
+- no unresolved blocker, required evidence gap, or route-changing assumption is hidden by the checkpoint claim;
+- the checkpoint remains authorized and useful for rollback, integration, handoff, or repository workflow.
+
+When review or evidence leaves unresolved work, return it to Workflow rather than deciding readiness here. If the user explicitly requests a preservation checkpoint of incomplete, unverified, blocked, or inconclusive work, label that state honestly and include only what is safe and useful to preserve. The commit does not authorize crossing the unresolved boundary.
 
 ## Inspect
 
-Before staging or committing, inspect:
+Inspect before staging or committing:
 
 ```bash
 git status --short
@@ -36,63 +41,66 @@ git diff --cached
 git ls-files --others --exclude-standard
 ```
 
-Diff evidence beats intent. If the worktree contains changes outside the requested scope, treat them as unrelated until proven otherwise.
-
-## Staging Rule
+Diff evidence beats “staged,” “commit everything,” “push all,” “exactly as-is,” or “do not leave leftovers.” Treat unrelated changes as user-owned until proven otherwise.
 
-Never use broad staging when unrelated, unreviewed, generated, or user-owned changes are present.
+## Stage Narrowly
 
-Avoid `git add .` and `git add -A`.
+Stage explicit paths or hunks that implement the coherent checkpoint.
 
-Stage explicit paths or hunks that match the completed task.
+Avoid `git add .` and `git add -A` when unrelated, unreviewed, generated, sensitive, or user-owned changes are present.
 
-If files are already staged, verify they belong in this commit. Do not preserve mystery staged changes just because they are staged.
+Verify existing staged changes rather than inheriting them blindly. Do not unstage, rearrange, discard, or overwrite user-owned changes merely to manufacture a clean commit without permission.
 
 ## Stop
 
-Stop before committing when:
+Stop before commit or push when:
 
-- staged changes include unrelated or unreviewed work
-- unstaged changes make the intended commit ambiguous
-- a user-owned change may be included accidentally
-- generated files, logs, debug output, or secrets appear without evidence they should be committed
-- pre-commit, lint, test, build, or formatter checks fail
-- the requested commit would mix separable product/code/doc/test concerns in a way that hurts review or rollback
+- included changes are unrelated, unreviewed when review is required, or outside the accepted outcome;
+- staged and unstaged edits make commit ownership ambiguous;
+- logs, debug output, secrets, generated artifacts, lockfiles, or formatter churn lack evidence they belong;
+- durable docs and implementation describe different behavior or authority;
+- verification failed or proves less than the commit message would claim;
+- the commit mixes separable concerns in a way that harms review, diagnosis, or rollback;
+- product, security, privacy, billing, permissions, data-loss, compatibility, public API, migration, or architecture behavior changed without an explicit decision.
 
-Name the blocker and ask which path to follow. If a clean narrow commit is possible without touching unrelated work, make it and leave unrelated changes untouched.
+Use [Decision Gate](../decision-gate/SKILL.md) when the safe commit path depends on an owner or source-truth decision. If a clean narrow commit is possible without touching unrelated work, prefer it and report what remains.
 
 ## Commit Shape
 
-Keep commits small enough to review, debug, and roll back.
+Keep the checkpoint independently understandable and revertible.
 
-Use the repo's existing commit style. If none is obvious, use a short imperative subject:
+Use the repo's established message style. Otherwise use a short imperative subject. Add a body only when source context, tradeoffs, residual risk, or the reason for the checkpoint would not be clear from the diff.
 
-```text
-Fix settings title typo
-```
+Reference specs, plans, ADRs, issues, or decisions only when they materially explain the change. Do not invent metadata conventions.
 
-Add a body only when it helps future readers understand why.
+A learning-slice commit must distinguish diagnostic or exploratory output from production behavior. A deepening commit should not silently change behavior. A delivery commit should name the behavior it adds or changes.
 
-Reference specs, plans, ADRs, issues, or decisions when they materially explain the commit. Do not invent mandatory `Refs:` lines for repos that do not require them.
+## Push
 
-## Push Rule
+Push only inspected commits when the user request and branch state make the route clear.
 
-Push only commits you inspected. Before pushing, inspect branch, upstream, remote, and ahead/behind state.
-Do not push to protected/shared branches, set upstream, use `--force`, or rewrite remote history unless explicitly requested and branch evidence supports it. Use `--force-with-lease` only for an intended rewrite of the user's own branch.
-If branch state is stale, diverged, missing upstream, or likely needs PR/CI/release judgment, stop and ask.
+Before pushing, inspect branch, upstream, remote, and ahead/behind state. Stop before protected/shared branches, upstream changes, force pushes, remote-history rewrites, divergence, or release/PR decisions that were not explicitly requested.
 
-## After Commit Or Push
+Use `--force-with-lease` only for an intended rewrite of the user's own branch with explicit approval and supporting branch evidence.
 
-Verify what landed:
+## Verify The Checkpoint
+
+After commit or push, inspect:
 
 ```bash
 git show --stat --oneline --name-only HEAD
 git status --branch --short
 ```
 
-Final response should state:
+Report:
+
+- commit SHA and subject;
+- what the checkpoint contains;
+- verification and review evidence;
+- push result when applicable;
+- remaining staged, unstaged, untracked, unpushed, or unverified work;
+- recommended next route.
+
+When a Working Record exists, use [Track Work](../track-work/SKILL.md) to record the commit SHA, checkpoint result, remaining state, and next useful action.
 
-- commit SHA, subject, and push result if pushed
-- what was committed
-- what verification supports it
-- any remaining uncommitted, unpushed, or unverified changes
+Do not continue to the next slice, push, or integrate merely because the commit succeeded. Return the result to [Workflow](../workflow/SKILL.md), or use [Finish Branch](../finish-branch/SKILL.md) when branch closeout is selected.

package/skills/commit-work/references/staging-decisions.md

@@ -1,51 +1,73 @@
 # Staging Decisions
 
-Use this for mixed staged sets, generated files, durable docs, or broad commit/push pressure.
+Use this when staged state is mixed, generated files or durable docs appear, broad commit/push language conflicts with the diff, or producing a narrow checkpoint may touch user-owned work.
 
 ## Evidence First
 
-Read staged, unstaged, and untracked state before deciding what to commit or push:
+Inspect:
 
 - `git status --short`
 - `git diff --cached`
 - `git diff`
 - `git ls-files --others --exclude-standard`
 
-Diff evidence beats "staged means ready", "commit everything", "push all changes", and "include all leftovers".
+Diff evidence beats “staged means ready,” “commit everything,” “push all changes,” and “include every leftover.”
 
-## Mixed Staged Sets
+## Classify Paths
 
-Staged changes can still be wrong.
+For each changed path, classify:
 
-Stop or make a narrow commit when the staged set mixes separable concerns, such as:
+- **Checkpoint:** directly implements or proves the intended slice.
+- **Required generated output:** repo convention or task requires it and its generator is known.
+- **Durable artifact:** Spec, policy, ADR, or Plan that belongs to the same accepted checkpoint while retaining its own authority and lifecycle.
+- **Durable continuation memory:** Working Record or Handoff describing the same checkpoint without becoming authority over live evidence.
+- **Related but separable:** useful work that should remain outside this checkpoint.
+- **Unrelated or user-owned:** not part of the current outcome.
+- **Sensitive or unsafe:** secrets, private data, debug output, destructive state, or unclear generated content.
 
-- release note or copy edits plus product behavior
-- source code plus local debug output
-- generated files plus hand edits
-- source-truth docs plus implementation changes that have not been confirmed
-- security, billing, permissions, privacy, migration, or public API behavior with unrelated work
+Do not infer ownership from staging state.
 
-If a sensitive staged change conflicts with docs, tests, policy, or contracts, do not commit it just because it is staged.
+## Narrow Checkpoint
 
-## Narrow Commit Rule
+A narrow commit is safe when:
 
-Make a narrow commit only when:
+- an explicit request, user-approved Plan, or explicitly approved discussion authorizes the local checkpoint;
+- its outcome and source requirement are clear;
+- every included path belongs to that outcome;
+- verification supports the claim represented by the commit;
+- selected review status is known and [Workflow](../../workflow/SKILL.md) supports the checkpoint route;
+- excluded changes can remain untouched without loss;
+- the final report names remaining dirty state.
 
-- the intended scope is clear
-- the included files are all part of that scope
-- excluded changes can remain staged or dirty without being lost
-- the final response reports remaining staged/dirty/untracked work
+Plan approval does not prove that every current path belongs. Stage explicit paths or hunks. If narrowing requires unstaging, rearranging, regenerating, or modifying user-owned work, stop unless the user or repo workflow already authorized that operation.
 
-If excluding files would require unstaging or rearranging user-owned work, ask first unless the repo clearly supports a safe path.
+## Mixed Concerns
+
+Separate changes when combining them harms review, diagnosis, or rollback, especially:
+
+- behavior plus unrelated refactoring;
+- source code plus local debug output;
+- generated artifacts plus unexplained hand edits;
+- durable source-truth changes plus implementation that has not been confirmed;
+- security, privacy, billing, permissions, migration, data-loss, compatibility, or public API behavior plus unrelated work;
+- learning-slice evidence plus production changes that have not passed promotion criteria.
+
+A single coherent behavior with its tests and matching docs may belong together.
 
 ## Generated Files
 
-Do not commit generated files, logs, snapshots, lockfiles, build outputs, or formatter churn unless the task or repo convention makes them part of the intended change.
+Commit generated files, snapshots, lockfiles, build outputs, or formatter changes only when the task or repo convention makes them part of the checkpoint.
+
+Name the generator or command that produced required output. Do not hand-edit generated files unless the repo explicitly expects it.
+
+## Durable Artifacts
+
+Specs, policies, and ADRs may govern behavior. Plans preserve approved strategy; Working Records and Handoffs preserve memory. Include any of them with code only when they belong to the same coherent checkpoint and their own maintenance rules support the change.
 
-If generated output is required, name the generator or verification that produced it.
+Do not revise a durable artifact merely to make the commit appear coherent. Return a material inconsistency to [Workflow](../../workflow/SKILL.md); use [Decision Gate](../../decision-gate/SKILL.md) when one user-owned choice or source conflict blocks the checkpoint.
 
-## Durable Docs
+## Existing Staged State
 
-Durable specs, ADRs, policies, handoffs, and runbooks are source truth. Commit them with code only when they describe the same confirmed change.
+Existing staged changes may belong to another workflow. Inspect them, but do not silently unstage, amend, discard, or absorb them.
 
-If a durable doc changes policy, status, ownership, public API behavior, billing, privacy, security, data loss, migration, or compatibility, treat that as a user-owned decision unless already confirmed.
+When ownership remains ambiguous, present the smallest safe staging options and ask which checkpoint the user wants.

package/skills/decision-gate/SKILL.md

@@ -0,0 +1,48 @@
+---
+name: decision-gate
+description: Use when proceeding would silently choose for the user, conflict with existing code, tests, docs, or requirements, or take a materially different path from what was requested or agreed.
+---
+
+# Decision Gate
+
+Stop before making a decision that belongs to the user or quietly changing the agreed path.
+
+The [Interaction Contract](../../runtime/interaction-contract.md) governs whether the user is asking, proposing, reasoning, or authorizing action. Decision Gate begins only after one blocking choice or conflict is clear. When the problem or alternatives still need broader exploration, read [Discuss](../discuss/SKILL.md) instead.
+
+## Stop Here
+
+Use the gate when:
+
+- the user must choose product behavior, scope, priorities, public interfaces, compatibility, permissions, security, privacy, billing, data-loss behavior, migration direction, or another hard-to-reverse outcome;
+- the request conflicts with existing code, tests, docs, policies, requirements, or established behavior;
+- the proposed action would materially change what was requested or agreed, including its evidence quality, risk, cost, persistence, or user-visible result;
+- new evidence exposes one known user choice or source conflict that must be resolved before proceeding.
+
+Do not use the gate for facts that can be inspected, harmless local choices, or reversible implementation details that preserve the accepted outcome.
+
+## Inspect Before Asking
+
+Inspect code, tests, docs, policies, logs, repository state, or current external sources when they can answer the factual part of the problem.
+
+Ask the user only for a choice that remains theirs. If you cannot state the decision and meaningful alternatives clearly, the option space is not ready for a gate; use Discuss.
+
+## Ask One Direct Question
+
+State:
+
+1. what was requested or previously agreed;
+2. the conflicting evidence, missing choice, or materially different path;
+3. why it changes the next action;
+4. the meaningful options and tradeoffs;
+5. a recommendation when evidence supports one;
+6. one direct question that resolves the block.
+
+Then stop. Do not perform the blocked action in the same response.
+
+Urgency, approval to continue, reviewer confidence, or existing practice does not resolve an unnamed decision or conflict.
+
+## Exit
+
+Exit when the choice is explicit, the conflict is resolved, and remaining uncertainty would not change the next safe action.
+
+Preserve the decision accurately for the work that depends on it. Do not broaden the decision or treat it as approval for a different path.