@hassangameryt/freeflow 0.5.0 → 0.7.0

package/skills/commit-work/references/simple-push.md

@@ -0,0 +1,92 @@
+# Simple Push
+
+Read this before performing any push through Commit Work.
+
+A **simple push** sends inspected local commits from the current named branch to one explicit or established remote branch without force, deletion, tag publication, integration, pull-request creation, release, or deployment.
+
+Use [Finish Branch](../../finish-branch/SKILL.md) when the route requires choosing how to integrate, share, preserve, rewrite, or clean up branch state.
+
+## Confirm Push Authority
+
+Push requires authority separate from local commit.
+
+Confirm:
+
+- which commits are intended;
+- the local branch;
+- the destination remote and branch;
+- whether setting a new upstream is included;
+- that no force, deletion, tag, or history rewrite is implied.
+
+Do not infer a remote, destination branch, pull-request target, or shared-branch policy when the wrong choice could affect collaborators.
+
+## Inspect The Route
+
+Inspect:
+
+```bash
+git branch --show-current
+git status --short --branch
+git branch -vv
+git remote -v
+git log -1 --oneline --decorate
+```
+
+When an upstream exists, inspect:
+
+```bash
+git rev-parse --abbrev-ref --symbolic-full-name @{upstream}
+git rev-list --left-right --count @{upstream}...HEAD
+```
+
+Ahead/behind state is only as fresh as the local remote-tracking reference. Do not claim current remote state unless it was freshly observed.
+
+Stop before pushing when:
+
+- `HEAD` is detached;
+- destination or upstream is unclear;
+- unexpected commits or dirty state change the route;
+- protected or shared-branch policy disallows the push or leaves its route unclear;
+- local and observed upstream history diverge;
+- the push would require force, deletion, tag publication, or another separately controlled action.
+
+## Push The Exact Branch
+
+Use the established upstream when it clearly matches the approved route.
+
+When no upstream exists, set one only when the remote and branch destination are explicit and the configuration change is included in the accepted route.
+
+Do not push additional branches or tags.
+
+A force push is not a simple push. Return an explicitly requested history rewrite to Workflow or Finish Branch.
+
+## Handle Rejection Without Escalation
+
+If the push is rejected or fails:
+
+- preserve the complete result;
+- do not automatically pull, merge, rebase, force, change remotes, or change destination;
+- inspect whether any remote update occurred;
+- return authentication, divergence, policy, or destination decisions to [Workflow](../../workflow/SKILL.md) or Finish Branch.
+
+A failed push does not invalidate the local commit.
+
+## Verify And Report
+
+After a successful push, inspect:
+
+```bash
+git status --short --branch
+git branch -vv
+```
+
+Report:
+
+- pushed commit range;
+- remote and destination branch;
+- whether an upstream was created or changed;
+- command result and strongest observed remote-state evidence;
+- remaining unpushed commits or dirty state;
+- CI, review, integration, release, or deployment work not established by the push.
+
+A successful push proves transfer to the observed destination. It does not prove pull-request creation, merge, release, deployment, or remote CI success.

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

@@ -1,73 +1,106 @@
 # Staging Decisions
 
-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.
+Read this when staged, unstaged, or untracked changes have mixed ownership or concerns; a path contains both included and excluded work; existing staged ownership is uncertain; generated, durable, sensitive, or suspicious files appear; or narrowing may require changing existing staged state.
 
-## Evidence First
+This reference determines what may enter the checkpoint. It does not establish commit authority, verification, review readiness, or permission to alter user-owned work.
 
-Inspect:
+## Classify The Changed Units
 
-- `git status --short`
-- `git diff --cached`
-- `git diff`
-- `git ls-files --others --exclude-standard`
+Classify at the path level only when the whole path has one role. Otherwise classify individual hunks.
 
-Diff evidence beats “staged means ready,” “commit everything,” “push all changes,” and “include every leftover.”
+- **Checkpoint content:** directly implements or proves the checkpoint claim.
+- **Required companion:** tests, documentation, schema, metadata, or generated output required for that same claim.
+- **Related but separable:** useful work that does not need to be preserved in this checkpoint.
+- **Unrelated or user-owned:** work outside the accepted outcome or whose ownership is not established.
+- **Sensitive or unsafe:** secrets, credentials, personal data, environment files, debug output, destructive state, or unexplained artifacts.
+- **Unclear:** content whose purpose, generator, ownership, or evidence relationship is not yet supported.
 
-## Classify Paths
+Only checkpoint content and required companions belong.
 
-For each changed path, classify:
+A broad request such as "commit everything" may authorize broad inclusion, but it does not remove the obligation to inspect unsafe, unclear, or unexpectedly unrelated content.
 
-- **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.
+## Protect Existing Staged State
 
-Do not infer ownership from staging state.
+Existing staged changes may belong to another workflow.
 
-## Narrow Checkpoint
+Inspect them, but do not infer that they are intended merely because they are staged. Do not silently:
 
-A narrow commit is safe when:
+- absorb them into the checkpoint;
+- unstage or reset them;
+- amend them into another commit;
+- move them through a stash or temporary commit;
+- replace the index or use index tricks to bypass ownership ambiguity.
 
-- 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.
+When intended and pre-existing staged work cannot be separated without manipulating ambiguous state, present the smallest safe options and ask which checkpoint the user wants.
 
-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.
+## Handle Partial Files Carefully
 
-## Mixed Concerns
+A file may contain both checkpoint and excluded hunks. Stage only the intended hunks when their behavior and evidence remain independently coherent.
 
-Separate changes when combining them harms review, diagnosis, or rollback, especially:
+Stop when:
 
-- 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.
+- included and excluded hunks depend on each other;
+- partial staging would produce an invalid intermediate state;
+- verification ran against the combined working tree and excluded changes may have affected the result;
+- the staged version differs materially from the state that was reviewed or verified.
 
-A single coherent behavior with its tests and matching docs may belong together.
+Do not claim an isolated staged checkpoint is supported merely because the combined dirty worktree passed.
 
-## Generated Files
+## Include Generated Files Deliberately
 
-Commit generated files, snapshots, lockfiles, build outputs, or formatter changes only when the task or repo convention makes them part of the checkpoint.
+Include generated files, snapshots, lockfiles, formatter output, or build artifacts only when repository convention or the accepted outcome requires them.
 
-Name the generator or command that produced required output. Do not hand-edit generated files unless the repo explicitly expects it.
+Establish:
 
-## Durable Artifacts
+- which command or generator produced them;
+- whether their changes are expected from the accepted source change;
+- whether they are deterministic enough to review;
+- whether hand edits are prohibited;
+- whether their verification belongs to the checkpoint evidence.
 
-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.
+Do not include generated output merely because it changed. Do not hand-edit it unless the repository explicitly expects that workflow.
 
-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.
+## Preserve Durable Artifacts Honestly
 
-## Existing Staged State
+A Spec, Plan, ADR, policy, public documentation file, or release artifact may have authority and maintenance rules independent of implementation.
 
-Existing staged changes may belong to another workflow. Inspect them, but do not silently unstage, amend, discard, or absorb them.
+Include it only when:
 
-When ownership remains ambiguous, present the smallest safe staging options and ask which checkpoint the user wants.
+- its change is explicitly covered;
+- it belongs to the same coherent checkpoint;
+- it describes the same accepted behavior;
+- its own maintenance policy permits the update.
+
+Do not edit a durable artifact merely to make implementation appear coherent. Return contradictions to [Workflow](../../workflow/SKILL.md).
+
+Working Records under `.freeflow/tasks/**` are ignored local memory and must never be staged or committed.
+
+## Reject Sensitive Or Suspicious Content
+
+Stop before staging:
+
+- secrets, tokens, credentials, private keys, or local environment files;
+- databases, dumps, recordings, or personal data;
+- unexplained binaries or generated archives;
+- logs, traces, screenshots, or debug output not explicitly required;
+- destructive state or files whose inclusion could expose or lose user data.
+
+Do not "clean up" suspicious files by deleting or discarding them. Preserve their state and report the exact paths.
+
+## Verify The Candidate
+
+After staging, compare all three states:
+
+```bash
+git diff --cached
+git diff
+git status --short --branch
+```
+
+The checkpoint is narrow only when:
+
+- the index contains exactly the intended checkpoint;
+- excluded work remains untouched;
+- remaining dirty state is understood;
+- verification still supports the staged version rather than only the combined worktree;
+- the final report can name everything left behind.

package/skills/decision-gate/SKILL.md

@@ -1,48 +1,106 @@
 ---
-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.
+name: "decision-gate"
+description: "Use when proceeding would silently choose a consequential outcome for the user, or when accepted sources conflict in a way that leaves one material choice blocking the next action."
 ---
 
 # Decision Gate
 
-Stop before making a decision that belongs to the user or quietly changing the agreed path.
+Resolve one known blocking decision without making it for the user.
 
-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.
+A **blocking decision** is a choice whose realistic answers materially change the accepted outcome, scope, behavior, risk, persistence, compatibility, evidence boundary, or next safe action.
 
-## Stop Here
+Decision Gate is not general discussion, factual investigation, or an approval checkpoint for routine work. It begins only when one blocking choice or source conflict is clear enough to resolve with one direct question.
 
-Use the gate when:
+The [Interaction Contract](../../runtime/prompts/interaction-contract.md) governs whether the user is asking, proposing, deciding, or authorizing action. [Workflow](../workflow/SKILL.md) owns authority and routing.
 
-- 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.
+## Enter With One Decision
 
-Do not use the gate for facts that can be inspected, harmless local choices, or reversible implementation details that preserve the accepted outcome.
+Use Decision Gate only when:
 
-## Inspect Before Asking
+- the requested or accepted path is known;
+- one unresolved choice or material source conflict can be stated precisely;
+- available evidence and established source precedence do not already settle it;
+- different realistic answers would materially change what follows;
+- proceeding would silently decide for the user or override accepted source truth.
 
-Inspect code, tests, docs, policies, logs, repository state, or current external sources when they can answer the factual part of the problem.
+Do not use Decision Gate for:
 
-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.
+- facts available through focused passive inspection;
+- reversible implementation details that preserve the accepted outcome;
+- ordinary authorization for one clear additional action;
+- preferences that do not affect the result or its acceptance;
+- hypothetical edge cases without supported reachability or consequence;
+- broad or unsettled option spaces that still require exploration.
+
+Use [Discuss](../discuss/SKILL.md) when the problem, alternatives, assumptions, or direction are not yet bounded enough for one decision.
+
+When several decisions appear, ask only the earliest one whose answer determines whether the others remain relevant. Do not turn the gate into an interview.
+
+## Resolve Facts Before Asking
+
+Inspect the smallest existing evidence that can settle the factual part: the current request, accepted decisions, code, tests, documentation, Specs, policies, ADRs, repository state, supplied artifacts, and current primary sources when relevant.
+
+Do not ask the user to choose between factual claims whose truth can be established from available evidence.
+
+When accepted sources appear to conflict:
+
+1. state each source's exact claim and applicable scope;
+2. determine whether each is current, accepted, draft, historical, generated, or advisory;
+3. apply repository-defined precedence or maintenance policy when one exists;
+4. identify the observable consequence of following each claim.
+
+A difference is material only when applicable sources make incompatible claims and selecting between them changes the accepted result or next safe action.
+
+Do not invent a universal hierarchy: code is not automatically correct because it runs, tests are not automatically requirements because they fail, documentation is not automatically stale because implementation differs, and task memory does not override live accepted source truth.
+
+If established precedence resolves the conflict, return the supported result to Workflow without asking a decision question. Updating an inconsistent source belongs to its owning activity and requires its own authority.
+
+If responsible framing requires new active evidence, return the exact claim, proposed observer, expected evidence, and stop condition to Workflow. Decision Gate does not run an experiment merely to make its question easier.
 
 ## Ask One Direct Question
 
-State:
+State proportionately:
 
-1. what was requested or previously agreed;
-2. the conflicting evidence, missing choice, or materially different path;
+1. the requested or previously accepted path;
+2. the exact missing choice or conflicting evidence;
 3. why it changes the next action;
-4. the meaningful options and tradeoffs;
+4. the realistic options and material tradeoffs;
 5. a recommendation when evidence supports one;
 6. one direct question that resolves the block.
 
+Frame the choice around the outcome the user owns, not ordinary implementation mechanics. Do not ask which file to change when the real decision is which behavior or contract should govern.
+
+Do not manufacture a menu. Omit dominated, unsafe, unavailable, or hypothetical options. A direct yes-or-no question is appropriate when one supported deviation needs a decision. Include preserving the current behavior, waiting, or stopping only when each is real.
+
+Recommend plainly when one path is better supported. State its principal tradeoff and what evidence or changed priority would alter the recommendation. A recommendation is not the user's decision.
+
 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.
+Urgency, prior effort, reviewer confidence, common practice, or general approval to continue does not resolve an unnamed decision or source conflict.
+
+## Interpret And Return The Decision
+
+Treat an explicit choice as resolving only the decision that was asked. A question, criticism, hypothesis, preference, conditional answer, or request for more information is not automatically a decision; respond to its substance and keep the blocked action stopped.
+
+Route narrowly:
+
+- explicit choice with a clear covered path → Workflow;
+- answer that reopens alternatives or assumptions → Discuss;
+- unresolved factual evidence → Workflow and the appropriate evidence owner;
+- defer, preserve, or stop → return that outcome without forcing progress.
+
+A resolved decision may complete the missing intent for a still-valid request. It does not authorize unrelated effects or another outcome by implication.
+
+Return to Workflow with:
+
+- the exact decision and who or what established it;
+- the selected outcome and important exclusions;
+- material consequences and affected source truth;
+- remaining uncertainty or revisit condition;
+- the authority state of the next action.
 
-## Exit
+When losing the decision or its rationale could cause later misalignment, Workflow may route [Track Work](../track-work/SKILL.md) to preserve it. Decision Gate does not mutate task memory itself.
 
-Exit when the choice is explicit, the conflict is resolved, and remaining uncertainty would not change the next safe action.
+Do not broaden the answer, reinterpret it as approval for a different path, or continue past another separately controlled boundary.
 
-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.
+Stop when one direct question has been asked and no answer exists, the answer does not resolve the material block, the appropriate decision owner is unavailable, or active evidence is required before a responsible choice can be framed. A supported wait, deferment, preservation boundary, or stop is a valid result.