Commit

Commit The Work

$fw:commit closes Flywheel's compact project loop between "the repo change is ready enough to finish" and "the branch is pushed with an open or refreshed PR."

It is the finishing workflow for:

• staged or unstaged work that needs commit planning, commit creation, push, and PR creation or refresh
• committed work that needs pushing and PR creation or refresh
• a feature branch that needs a PR
• an existing PR whose description should be refreshed
• a branch that surfaced durable lessons worth capturing before commit

Use it after $fw:work or after $fw:review reaches a clean enough verdict. For runtime-risky changes, use it after $fw:rollout sets the activation, validation, and rollback posture. If the user invokes $fw:commit directly, treat that as permission to run the finish-stage workflow rather than as a reason to reject the request because earlier stages were skipped.

Interaction Method

Follow ../references/host-interaction-contract.md.

Call the exact host question tool named in ../references/host-interaction-contract.md when that tool is available. Do not ask for raw 1/2/3 replies when the host already offers a choice surface.

When the workflow spans multiple material steps, use the host task-tracking tool named in ../references/host-interaction-contract.md to create and maintain a short task list.

Ask one question at a time. When multiple finish paths are viable, present a short predicted choice list with the recommended label first and rely on the host's native freeform final path when it exists.

Input

#$ARGUMENTS

Parse optional tokens before interpreting any remainder:

• local-only - explicitly opt out of the default publish path; create local commit(s) but do not push or create or refresh a PR
• plan:<path> - use this plan as finish-stage context and update it to status: completed when appropriate
• pr:<url> - target this existing PR explicitly
• refresh-description - update the current PR description without changing branch or commit state

Reference Loading Map

Do not preload every support file. Load only what the current phase needs:

• read references/pr-body-template.md only when composing or refreshing the PR body
• read references/evidence-bundle.md when a shared evidence bundle exists or when a proof-producing stage already created reusable evidence for this branch
• read ../rollout/references/rollout-template.md only when a rollout artifact already exists and its staged-release summary should be reflected in the PR story
• read ../observability/references/service-readiness-matrix.md only when the change is runtime-risky and the monitoring or validation section needs a grounded readiness frame
• read ../references/workflow-gates.md before final readiness checks and when closing the finish stage
• read .flywheel/config.local.yaml when present for repo-local commit gates such as browser proof, review-before-commit, and runtime validation

Core Principles

1. Finish from repo truth - branch status, open PR state, test evidence, and review outcomes outrank memory or optimism.
2. Commit honestly - use $fw:commit-message for each logical unit being committed. If the helper is unavailable, draft the conventional header directly and ask before marking breaking changes.
3. Prefer one coherent finish flow - local commits, push, PR state, and operational validation belong to one remembered command.
4. Publish by default - unless the user passes local-only, continue from commit through push and PR creation or refresh instead of stopping at a clean local branch.
5. Preview multiple commits before execution - when the diff should split, show a short commit plan first so the grouping is reviewable.
6. Operational validation is mandatory - every PR gets a Post-Deploy Monitoring & Validation section, even if the answer is a no-impact rationale.
7. Preserve branch safety - do not commit directly to the default branch without explicit user approval.
8. Carry only the material architecture and code-quality story - PR text should explain the relevant boundary, pattern, simplification, or maintainability decisions without replaying raw specialist analysis.
9. Capture durable lessons before commit - when the branch surfaced durable project value, offer spin before staging and committing so the solution doc can land in the same logical change.
10. Stop only for real blockers - do not prompt or pause for preferences that can be inferred from repo truth. Stop for unsafe default-branch state, failed required checks, missing required policy gates, unavailable publish tooling, unresolved blocking review findings, missing required proof, or an explicit local-only request.

Workflow

Phase 1: Gather Finish Context

Collect the smallest useful context in one pass:

printf '=== STATUS ===\n'; git status --short --branch
printf '\n=== BRANCH ===\n'; git branch --show-current
printf '\n=== DIFF ===\n'; git diff HEAD
printf '\n=== LOG ===\n'; git log --oneline -10
printf '\n=== DEFAULT_BRANCH ===\n'; git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null || echo 'DEFAULT_BRANCH_UNRESOLVED'
printf '\n=== PR_CHECK ===\n'; gh pr view --json url,title,state,baseRefName,headRefName 2>/dev/null || echo 'NO_OPEN_PR'

If GitHub CLI is unavailable or unauthenticated, continue only as far as local git truth allows and report PR creation or refresh as a publish blocker. Do not silently downgrade the default finish path to local-only unless the user passed local-only.

If .flywheel/config.local.yaml exists, read only the finish-stage-relevant keys before classifying the path:

• review.require_review_before_commit
• browser.require_proof_for_browser_visible_changes
• commit.require_browser_proof_for_browser_visible_changes
• runtime.require_operational_validation_for_runtime_changes

If .context/flywheel/evidence/ exists, inspect only the newest summary.md that clearly matches the current branch, plan, or task. Treat the shared bundle as the primary reusable proof source for finishing.

If .context/flywheel/rollout/ exists, inspect only the newest rollout.md that clearly matches the current branch, plan, or task. Treat it as the source of truth for activation sequence, validation window, and rollback trigger.

Phase 2: Classify The Finish Path

Choose the path from branch truth. The default non-local path is publish complete: commit what is needed, push the branch, then create or refresh the PR.

• Description refresh - user asked for refresh-description or only wants to update the existing PR text
• Full finish - branch has uncommitted work, unpushed commits, no open PR, or an existing PR whose body should reflect new commits, evidence, or summary
• Local-only finish - user explicitly asked for local-only
• Publish finish - branch is committed but still needs push plus PR creation or refresh
• PR refresh - branch is already pushed and an open PR exists; refresh it by default when the current finish payload differs from the PR body

If the current branch is the default branch and finishing would create commits, create a feature branch first unless the user explicitly approves committing on the default branch.

If a clean isolated checkout is preferable before finishing, use $fw:worktree instead of switching the shared checkout ad hoc.

Phase 3: Run Missing Readiness Checks

Read ../references/workflow-gates.md and apply the Commit-Ready gate while running the checks below. If the gate is not satisfied, stop with the missing items instead of committing, pushing, or creating a PR.

Before creating commits or a PR, confirm:

• tests and linting were addressed, using the repo-grounded commands already discovered during $fw:work or local setup
• browser-visible changes have fresh acceptance proof from $fw:browser-test, repo-native browser tests, or an explicit user decision to continue without that proof
• if the change is runtime-risky and activation sequence, validation window, or rollback trigger are still unresolved, stop and route through $fw:rollout before continuing
• the change's runtime impact has either:
  • concrete monitoring and validation notes, or
  • a clear no-impact rationale
• if local policy requires explicit operational validation for runtime changes, that validation is present before continuing

Review handling:

• if $fw:review already ran and the latest verdict is clean enough, reuse it
• if review has not run and finish-stage confidence depends on it, run $fw:review now instead of blocking only because the user skipped it
• if unresolved P0 or P1 gated or manual findings remain after review, stop instead of continuing into commit or PR creation
• if local policy requires review before commit, stop only when the review pass still leaves blocking findings unresolved

If the branch is not actually ready, stop and say what remains.

Phase 4: Run The Pre-Commit Spin Checkpoint

Before building the final commit payload or staging files, infer at most 3 candidate spin lessons from:

• execution evidence such as review findings, validation work, or non-obvious fixes
• repo changes that altered setup, CLI, API, config, docs, or workflow contracts
• answers and clarified preferences surfaced during ideate, brainstorm, or plan when they materially changed the repo workflow or project direction
• user corrections from this session that materially changed how Flywheel should behave for project work

Only keep candidates that look durable and project-specific. If nothing non-trivial surfaced, continue without forcing a spin offer.

If one or more candidates are worth preserving, call the host question tool with a small choice surface. Put the recommended option first:

1. Quick spin - capture the strongest lesson in a compact solution note
2. Full spin - run $fw:spin with the selected candidate summary
3. Skip - finish without capturing a solution entry

Recommend the strongest candidate explicitly when capture is warranted. Recommend Skip only when the value is marginal.

If the user wants to continue, launch $fw:spin with the selected candidate summary and the selected capture depth instead of calling it blank. For quick capture, pass a lightweight-mode hint with the summary. When $fw:spin creates or updates docs/solutions/, treat those files as part of the same finish payload and include them in the commit plan.

Phase 5: Build The Finish Payload

Assemble one finish summary from repo truth that will be reused in the PR Summary section and in the final user report. Keep it concise: what changed, why it matters, and any material architecture, code-quality, testing, decision, or operational caveat.

Assemble the payload for commit, push, and PR steps from:

• current diff and recent commits
• any docs/solutions/ changes created by the pre-commit spin checkpoint
• plan summary and key decisions when plan:<path> is available
• context or decision-record artifacts when they materially explain the branch
• the material architecture, pattern, simplification, or maintainability story when those decisions materially affect the branch summary
• testing notes
• review outcomes and residual caveats
• rollout artifact contents when present
• shared evidence bundle contents when present
• operational validation notes

When the change is runtime-risky, read ../observability/references/service-readiness-matrix.md so the PR's monitoring section covers the real contract, state, rollout, and recovery surface instead of generic "watch the logs" language.

If a shared evidence bundle exists, prefer it first. Include only items marked clean or redacted with PR Use: yes. Turn summary-only items into short prose instead of pasting raw artifacts. Keep local-only items out of the PR body.

If the change affects observable behavior and the repo or host already exposes evidence such as screenshots, CLI transcripts, request examples, generated artifacts, or a shared evidence bundle, offer three choices:

• Include existing evidence (recommended when a clean or redacted bundle entry already exists)
• Finish without evidence
• Freeform path when the repo needs a different evidence posture

Do not block finishing on evidence capture when the repo has no practical capture path.

Only include evidence in the PR description when you are above 90% confident it contains no secrets and no meaningful PII. Do not paste raw auth headers, cookies, tokens, passwords, or unredacted sensitive request or response bodies into the PR body. When the raw artifact is too sensitive but the shape matters, prefer a redacted or dummy-substituted example.

When a shared evidence bundle exists, cite the bundle-backed summary or the sanitized artifact path rather than re-explaining the proof from scratch.

When a rollout artifact exists, reuse its activation sequence, validation window, owner, and rollback trigger instead of rebuilding those decisions from memory during PR preparation.

If the change is browser-visible and fresh proof is still missing, route through $fw:browser-test before final PR preparation unless the user explicitly wants to continue without it.

Read references/pr-body-template.md and fill it with concrete repo facts.

Phase 6: Plan And Create Commit(s)

If the worktree is dirty:

1. identify one logical unit at a time
2. decide whether the diff should stay as one honest commit or split into multiple logical commits
3. if multiple commits are warranted, show a short commit plan before execution with:
   • the proposed header
   • the goal of the unit
   • the reason it is separate
4. if the diff is too entangled for a clean split, say so and prefer one honest commit
5. stage only the files for each chosen unit
6. use $fw:commit-message for each conventional header, plus body or footers when useful
7. commit the unit before moving to the next one

If the most honest message would be breaking, ask before using ! or BREAKING CHANGE:.

Default to one commit unless there are clearly separate concerns worth splitting.

Phase 7: Push

If the path is local-only, skip this phase and say so explicitly.

Otherwise publish the branch safely:

git push --set-upstream origin HEAD

If the branch already has an upstream, use git push.

If push fails, stop before PR creation or refresh and report the exact blocked state. Do not claim the branch is published unless the push succeeded.

Phase 8: Create Or Refresh The PR

If the path is local-only, skip this phase and report that no PR work was requested.

If GitHub CLI is available:

• No open PR -> create one with the assembled title and body after the branch has been pushed
• Existing open PR -> refresh the title and body with the assembled finish summary, testing, monitoring, and evidence unless the user explicitly asked for local-only behavior
• Description refresh -> update the existing PR title and body without changing branch or commit state

Required PR body sections:

• Summary
• Testing
• Post-Deploy Monitoring & Validation
• Evidence, only when present

If there is truly no runtime impact, the monitoring section must still contain:

No additional operational monitoring required.
Reason: <one line grounded in the actual change>

Phase 9: Close The Loop

When plan:<path> is available and the plan frontmatter contains status: active, update it to status: completed.

Then report:

1. finish summary
2. branch name, push result, and PR URL or explicit PR blocker
3. commits created or confirmed
4. any residual follow-up
5. whether the pre-commit spin checkpoint captured, skipped, or found no durable lesson
6. a final handoff card from ../references/workflow-gates.md with readiness, evidence, and any open follow-up

Do not make a normal post-commit spin offer. If push, PR creation, CI, or reviewer feedback after commit reveals a new durable lesson, treat that as a new follow-up change and capture it in a later commit.

If the branch finished from a .worktrees/ checkout and no longer needs that checkout, suggest $fw:worktree cleanup <branch> as the cleanup path.

Included References

Evidence Bundle

@./references/evidence-bundle.md

PR Body Template

@./references/pr-body-template.md

Rollout Template

@../rollout/references/rollout-template.md