docs-ssot git.instructions.md

Git Practices

Branch rules

• Never commit directly to main. All changes must go on a feature branch and be merged via PR. If you realise you are on main with uncommitted changes, stash them, create a branch, then pop:

  git stash
  git checkout -b feature/your-branch-name
  git stash pop
  

• Before creating a branch, sync main first.

  git checkout main
  git pull --rebase
  git checkout -b feature/your-branch-name
  

  Branching from a stale main causes the new branch to miss upstream commits, leading to conflicts and missing content when rebasing later.

Branch naming

Use the prefix that matches the change type:

Prefix	When to use
feature/	New capability or behaviour
fix/	Bug fix
refactor/	Code restructuring without behaviour change
chore/	Maintenance, dependency updates, config
docs/	Documentation only

Example: feature/human-interaction-points, fix/jq-precedence-bug

Commit messages

This repository uses Conventional Commits:

<type>(<optional scope>): <short summary>

Recognised types: feat, fix, refactor, perf, test, docs, chore

Examples from this repo:

• feat(skill): add effort-aware flow template selection
• fix(pre-tool-hook): correct jq precedence in skippedPhases check
• perf(pre-tool-hook): combine dual jq calls into single invocations
• chore: forge artifacts for refactor-scripts-maintainability

Resolving merge conflicts

• Check git status before any commit or branch operation. Unmerged paths block rebases and cause misleading errors.
• Never commit to main to resolve a conflict mid-pull. If git pull fails with conflicts, resolve them, then complete the merge with git commit — do not create new commits on top before the merge is finished.
• Keep the more complete/advanced version when resolving state.json conflicts. Pipeline state files (state.json) record progression; always keep the version with more completed phases.