@hassangameryt/freeflow 0.5.0 → 0.7.0

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,82 +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 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.
+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. 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.

package/skills/commit-work/SKILL.md

@@ -1,106 +1,145 @@
 ---
-name: commit-work
-description: Use when committing work, including selecting and staging the intended changes, creating and verifying the commit, or explicitly pushing committed work.
+name: "commit-work"
+description: "Use when creating an explicitly requested or selected local Git commit, including staging its exact contents, verifying the resulting checkpoint, or performing a separately authorized simple push."
 ---
 
 # Commit Work
 
-Commit an intended, coherent checkpoint. A commit preserves rollback and provenance; it does not prove correctness or approve the next route.
+Preserve one supported repository state as a coherent local Git checkpoint.
 
-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.
+Commit Work normally follows execution, verification, self-review, and any selected independent review. It preserves that supported state; it does not establish correctness, close the Slice, authorize another Slice, or imply push, integration, release, or launch.
 
-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.
+A commit is not mandatory merely because work finished. Enter only when the user explicitly requests a local commit or [Workflow](../workflow/SKILL.md) selects an authorized Local commit checkpoint.
 
-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).
+An explicitly requested preservation checkpoint may capture incomplete, failing, or inconclusive work. Describe that state honestly and do not treat the commit as permission to cross the unresolved boundary.
 
-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.
-
-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.
-
-## Route Check
+## Enter At The Commit Boundary
 
 Before staging, confirm:
 
-- 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.
+- local commit authority is explicit and still valid;
+- the checkpoint has one coherent claim;
+- the request, accepted decisions, and live changes still describe the same outcome;
+- fresh evidence supports the exact state being preserved, or this is an explicitly requested preservation checkpoint;
+- any selected independent review is complete and its material findings are adjudicated;
+- no unresolved decision, source conflict, or required evidence gap is hidden by the checkpoint claim.
+
+A Working Record may preserve checkpoint selection and authority but cannot create them. Approval to implement does not imply approval to commit.
 
-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.
+Commit Work verifies fidelity between the supported state and the Git checkpoint. It does not dispatch missing review, repair implementation, or generate missing behavioral evidence. Return those needs to Workflow.
 
-## Inspect
+## Inspect The Candidate State
 
-Inspect before staging or committing:
+Inspect before changing the index:
 
 ```bash
-git status --short
+git status --short --branch
+git status
 git diff
 git diff --cached
 git ls-files --others --exclude-standard
 ```
 
-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.
+Inspect submodule state when status reports a changed submodule.
 
-## Stage Narrowly
+Read [Staging Decisions](references/staging-decisions.md) when:
 
-Stage explicit paths or hunks that implement the coherent checkpoint.
+- staged, unstaged, or untracked changes have mixed ownership or concerns;
+- a path contains both intended and excluded changes;
+- existing staged ownership is uncertain;
+- generated, durable, sensitive, or suspicious files appear;
+- narrowing the checkpoint may require changing existing staged state.
 
-Avoid `git add .` and `git add -A` when unrelated, unreviewed, generated, sensitive, or user-owned changes are present.
+Read [Git State Edges](references/git-state-edges.md) when Git reports an in-progress operation, unmerged paths, detached `HEAD`, submodule ambiguity, or an empty candidate; a requested commit would amend, be empty, or bypass hooks; or any commit or hook fails.
 
-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.
+Treat staged state as evidence of index contents, not evidence of ownership, intent, verification, or readiness.
 
-## Stop
+## Build The Exact Checkpoint
+
+Stage only paths or hunks required to make the checkpoint claim true.
 
-Stop before commit or push when:
+Broad staging commands are acceptable only when every changed path has been inspected and belongs to the same checkpoint. Otherwise stage explicit paths or hunks.
 
-- 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.
+Do not silently unstage, rearrange, discard, overwrite, or absorb user-owned work to manufacture a clean commit.
+
+After staging, inspect the exact candidate:
+
+```bash
+git diff --cached
+git diff --cached --check
+```
 
-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.
+Confirm:
 
-## Commit Shape
+- every staged path and hunk belongs;
+- required tests, documentation, generated outputs, or metadata are present;
+- no unrelated, sensitive, unexplained, or user-owned content is included;
+- the staged diff is non-empty unless an empty commit was explicitly requested;
+- the commit claim does not exceed available verification and review evidence;
+- excluded working-tree changes do not invalidate evidence for the staged checkpoint.
 
-Keep the checkpoint independently understandable and revertible.
+Interpret `git diff --cached --check` against repository conventions. Unresolved conflict markers or unintended whitespace damage stop the commit; do not edit content merely to silence the command.
 
-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.
+If producing the exact checkpoint requires source changes, additional evidence, or a user-owned staging decision, return to Workflow rather than performing that work here.
 
-Reference specs, plans, ADRs, issues, or decisions only when they materially explain the change. Do not invent metadata conventions.
+## Create The Commit
 
-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.
+Use the repository's established commit-message style. Otherwise use a short imperative subject describing the actual checkpoint, not the wider task ambition.
 
-## Push
+Add a body only when the diff does not adequately explain material context, tradeoffs, residual risk, or why incomplete state is being preserved. Reference existing issues, Specs, Plans, or decisions only when they materially explain the checkpoint. Do not invent trailers or metadata conventions.
 
-Push only inspected commits when the user request and branch state make the route clear.
+Create an ordinary local commit from the inspected index.
 
-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.
+Do not use `--amend`, `--allow-empty`, or `--no-verify` by implication. Read Git State Edges when one is explicitly requested or becomes relevant.
 
-Use `--force-with-lease` only for an intended rewrite of the user's own branch with explicit approval and supporting branch evidence.
+If a hook fails, changes files or the index, or makes prior evidence stale, do not bypass or blindly retry it. Inspect the resulting state through Git State Edges.
 
 ## Verify The Checkpoint
 
-After commit or push, inspect:
+After Git reports a successful commit, inspect:
 
 ```bash
-git show --stat --oneline --name-only HEAD
-git status --branch --short
+git show --stat --oneline --decorate HEAD
+git show --format= --name-status HEAD
+git status --short --branch
 ```
 
+Confirm that:
+
+- the intended commit was created;
+- its subject and contents represent the checkpoint claim;
+- no unexpected staged, unstaged, or untracked state resulted;
+- remaining changes are known and were not silently absorbed.
+
 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.
+- the checkpoint claim and included scope;
+- verification and selected-review evidence;
+- whether the commit is complete or an honest preservation checkpoint;
+- remaining staged, unstaged, untracked, unverified, or unpushed work;
+- any hook, signing, identity, or repository limitation;
+- the route returned to Workflow.
+
+Return the checkpoint result to Workflow. When a Working Record exists, Workflow may route [Track Work](../track-work/SKILL.md) to record `commit:<sha>`, settle the selected checkpoint, and reconcile the Current Slice.
+
+Do not stage leftovers, begin another Slice, push, integrate, release, or clean up merely because the commit succeeded.
+
+## Push Only When Separately Authorized
+
+A local commit does not authorize push.
+
+Before any push, read [Simple Push](references/simple-push.md). Use [Finish Branch](../finish-branch/SKILL.md) instead when the request involves integration, pull-request strategy, branch cleanup, history rewriting, or choosing among branch-closeout routes.
+
+## Stop
 
-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.
+Stop and return the smallest blocking fact when:
 
-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.
+- commit authority or the checkpoint claim is unclear;
+- live changes no longer match the supported outcome;
+- selected review or required evidence remains unresolved;
+- the exact checkpoint cannot be staged without manipulating ambiguous user-owned state;
+- sensitive or unexplained content may be included;
+- Git is in a non-ordinary state whose intended outcome is unsettled;
+- creating the commit would require implementation changes, evidence generation, hook bypass, amendment, or history rewriting outside explicit authority;
+- push destination, upstream, or remote-history effect is unclear.

package/skills/commit-work/references/git-state-edges.md

@@ -0,0 +1,94 @@
+# Git State Edges
+
+Read this when Git reports an in-progress operation, unmerged paths, detached `HEAD`, submodule ambiguity, or an empty candidate; a requested commit would amend, be empty, or bypass hooks; or any commit or hook fails.
+
+These states can change the meaning or recoverability of a commit. Inspect before choosing a recovery action.
+
+## In-Progress Operations
+
+A commit during merge, rebase, cherry-pick, or revert may complete or advance that operation rather than create an ordinary checkpoint.
+
+Stop and establish:
+
+- which operation is active;
+- whether the current checkpoint is intended to conclude it;
+- whether all conflicts and behavior decisions are settled;
+- which owner should continue the operation;
+- what verification is required on the resulting state.
+
+Do not use Commit Work to finish an operation merely because Git currently permits `commit`.
+
+Unmerged paths always stop an ordinary commit.
+
+## Detached HEAD
+
+A detached-`HEAD` commit may be valid but can become difficult to recover or push.
+
+Before committing, require an explicit preservation route naming how the resulting commit will remain reachable. Use [Finish Branch](../../finish-branch/SKILL.md) when branch creation, integration, or checkout ownership must be decided.
+
+Do not silently create or switch branches.
+
+## Amend And Empty Commits
+
+`git commit --amend` rewrites an existing checkpoint. Use it only when the user explicitly requests amendment and the exact target commit, included changes, authorship effects, and remote-history state are known.
+
+If the target may already be shared or pushed, return to [Workflow](../../workflow/SKILL.md) or Finish Branch before rewriting it.
+
+Use `--allow-empty` only for an explicitly requested empty checkpoint with a named repository purpose. An accidentally empty index is not authorization for an empty commit.
+
+## Hooks
+
+Do not bypass hooks merely because they block the commit.
+
+When a hook fails:
+
+1. preserve its complete result;
+2. inspect `HEAD`, the index, and working tree;
+3. determine whether a commit was created despite the reported failure;
+4. determine whether the hook changed files or staged content;
+5. return implementation, verification, policy, or environment failures to their owning route.
+
+When a hook changes repository content, the previously supported state may no longer be the state being committed. Reinspect the complete diff and obtain affected verification before retrying.
+
+Use `--no-verify` only when the user explicitly requests that exact bypass and repository policy permits it. Report which checks were skipped and which claims therefore remain unsupported.
+
+## Commit Command Failures
+
+After any failed or interrupted commit attempt, inspect:
+
+```bash
+git status
+git diff
+git diff --cached
+git log -1 --oneline --decorate
+```
+
+Do not assume failure means no commit was created or no state changed.
+
+For identity, signing, credential-helper, editor, lock, filesystem, or permission failures:
+
+- do not change global or repository Git configuration without authority;
+- do not delete lock files while process ownership is unclear;
+- do not retry through a materially different command without a supported cause;
+- report the exact blocker and preserved state.
+
+Use [Diagnose Failure](../../diagnose-failure/SKILL.md) when the cause remains unclear or a retry repeats the failure.
+
+## Submodules
+
+A parent commit records a submodule pointer, not the submodule's uncommitted contents.
+
+Inspect:
+
+- the recorded pointer change;
+- whether the nested worktree is dirty;
+- whether the intended checkpoint includes the pointer update;
+- whether nested changes have their own preservation route.
+
+Do not claim nested changes are preserved by committing only the parent repository.
+
+## Return Safely
+
+Return to Commit Work only when the repository has one supported, recoverable checkpoint candidate.
+
+Otherwise preserve the exact Git state and return to Workflow, Finish Branch, Diagnose Failure, or the producing activity whose responsibility changed.