Imported from golifox/codex-skills (konsierge-git-flow/SKILL.md). Install upstream with npx skills add golifox/codex-skills --skill konsierge-git-flow. Copyright stays with the author.

Konsierge Git Flow

Treat this as the standing delivery workflow for Konsierge repositories.

This skill owns branch topology, commits, target integration, pushes, and delivery evidence. For commit-message selection and formatting, use konsierge-commit-conventions. That skill generates text only; this skill controls when and where the commit is created.

The global commit hook first identifies the repository. Repositories with any remote hosted exactly at gitlab.konsierge.com, or repositories explicitly configured with git config konsierge.commitPolicy true, use the KON rules below. Other repositories keep unrestricted branch names and require Conventional Commit subjects such as feat: add export or fix(api): reject invalid input; real Git merge and revert operations retain their generated subjects.

The global hook directory dispatches every standard Git hook back to an executable repository-local .git/hooks/<hook> when one exists. The global commit-msg policy runs first and then chains the repository-local commit-msg, so enabling policy enforcement must not silently disable existing project hooks.

A repository-local core.hooksPath overrides Git's global value before any global hook can run. Before every commit, inspect git config --local --get core.hooksPath. When it is set, do not commit until that hook manager explicitly invokes the Konsierge validator (or its effective commit-msg is installed with the global pre-commit config). This is an agent-side fail-closed preflight because Git provides no higher-precedence client-side hook. Never claim that the global installation covers a repository with an unintegrated local override.

Hard Rules

• Develop the feature and create its original commits in a ticket branch. A regular checkout may use either KON-XXXX or KON-XXXX-<kebab-case-description>. A linked worktree must use the descriptive form, for example KON-0000-passes-cancellation or KON-1234-authorization-implementation, so concurrent worktrees remain distinguishable.
• Use the concrete ticket from the request or current branch. When none exists, use KON-0000; add a kebab-case description whenever the work is performed in a linked worktree.
• Treat the contracts tree as out-of-scope by default. When the user did not explicitly ask to change contracts, ignore contracts completely: do not mention it in status/final reports, do not treat its dirty state as relevant, and do not include it in staging, commits, checks, or delivery decisions.
• Never commit feature work directly to dev or master.
• Never push task branches or their -dev delivery branches under any circumstance.
• By default, merge the completed feature branch locally into every delivery target that exists on origin: both dev and master, only dev, or only master.
• When KON-XXXX-dev already exists locally or on origin, or a direct KON-XXXX -> dev merge has conflicts that cannot be resolved safely, use the split delivery topology: merge KON-XXXX-dev into dev and the original KON-XXXX into master.
• Treat KON-XXXX-dev only as the dev integration branch. Update it from origin/dev; never merge it into master.
• Push only the delivery targets that exist on origin, after their local merges and checks succeed. If only dev exists, push only dev. If only master exists, push only master. Stop and ask for direction when neither exists.
• When both targets exist, always push them sequentially: push dev, require its successful staging deployment, then push master and require its successful production deployment. Never push both targets together or start their pipelines concurrently; their parallel test jobs share temporary database infrastructure and can delete each other's databases.
• Monitor pipelines and deployments only when the user explicitly requests monitoring or when both dev and master are being pushed. For a single-target push, verify the remote SHA and feature-commit containment, but do not monitor its deployment unless explicitly requested.
• Never force-push, rebase, or rewrite dev or master.
• Keep every merge commit message generated by Git. Never pass -m/--message to git merge or edit the default merge message.
• Merge only a local named task-branch ref. Never merge FETCH_HEAD, a raw commit SHA, a filesystem path, or a repository URL into a delivery branch. When importing a branch from another worktree or clone, fetch it, create the correctly named local branch ref, and merge that ref.
• Before pushing a delivery branch, inspect the merge subject. It must name only the task branch, for example Merge branch 'KON-0000-passes-cancellation' into dev, and must not contain FETCH_HEAD, .worktrees/, file://, a repository URL, or an absolute filesystem path.
• When deployment monitoring is required, treat delivery as incomplete until GitLab MCP confirms every monitored target's exact pushed SHA deployed successfully to its environment.

Prepare

1. Read repository instructions and inspect branch, status, staged/unstaged diffs, upstreams, recent subjects, and remote target state. Also inspect git config --local --get core.hooksPath; stop if a local override does not invoke the global commit policy.
2. Preserve unrelated and pre-existing changes. Do not switch branches with an unresolved dirty worktree.
3. Fetch origin before starting and determine whether dev, master, or both exist on the remote. Reuse the local task branch when present; otherwise create it from the repository's established base. If the base is genuinely ambiguous, ask.
4. Ensure a regular checkout branch matches KON-[0-9]+(?:-[a-z0-9]+(?:-[a-z0-9]+)*)?. In a linked worktree, require KON-[0-9]+-[a-z0-9]+(?:-[a-z0-9]+)*.

Commit in the Feature Branch

1. Implement and verify the requested work.
2. Build atomic commits using konsierge-commit-conventions. Nearby repository history remains authoritative when it establishes a more specific convention.
3. Confirm the feature worktree is clean and relevant checks pass.
4. Do not push the feature branch.

Merge Locally

Fetch origin again immediately before merging. First check which delivery targets exist and whether the matching task -dev branch exists locally or on origin. Apply the steps below only to existing target branches; skip every step for an absent target.

Default topology

When no KON-XXXX-dev branch exists and the feature branch merges into dev without unsafe conflicts:

1. Switch to dev, fast-forward it to origin/dev, merge the feature branch with the repository's established merge style, and run relevant checks.
2. Switch to master, fast-forward it to origin/master, merge the same feature branch, and run relevant checks.
3. Stop on conflicts, failed checks, non-fast-forward target state, or unexpected commits. Do not push a partial delivery.

Split -dev topology

Use this path when KON-XXXX-dev already exists or the direct feature-to-dev merge cannot be resolved safely. This is used by repositories such as CRM when dev and master require different integration branches.

1. Abort the conflicted direct merge into dev, if one is in progress.
2. Check out the existing KON-XXXX-dev branch, including from origin/KON-XXXX-dev when only the remote branch exists; otherwise create it from origin/dev.
3. Merge the current origin/dev into KON-XXXX-dev; do not rebase or reset the delivery branch. Bring over any missing feature commits from the original KON-XXXX with explicit cherry-picks, preserving the original feature branch for master.
4. Resolve integration differences only on KON-XXXX-dev, run the relevant checks there, then fast-forward local dev to origin/dev and merge KON-XXXX-dev into dev.
5. Fast-forward local master to origin/master and merge the original KON-XXXX into master.
6. Never merge KON-XXXX-dev into master or the original KON-XXXX into dev after selecting this topology. Stop if either integration still cannot be resolved safely.

Prefer explicit merge commits when that matches the repository history:

# Default topology and `master` in split topology
GIT_MERGE_AUTOEDIT=no git merge --no-ff KON-0000-passes-cancellation

# `dev` in split topology
GIT_MERGE_AUTOEDIT=no git merge --no-ff KON-0000-passes-cancellation-dev

GIT_MERGE_AUTOEDIT=no only suppresses the editor; it preserves Git's default merge message. Do not replace it with a custom message.

If the task branch came from another worktree or clone, bind the fetched object to its descriptive name before merging:

git fetch /absolute/path/to/source-worktree KON-0000-passes-cancellation
git branch --force KON-0000-passes-cancellation FETCH_HEAD
GIT_MERGE_AUTOEDIT=no git merge --no-ff KON-0000-passes-cancellation

Never use git merge FETCH_HEAD in the delivery branch: Git can expose the source filesystem path in the generated merge subject.

Push Targets

When both local target branches are correct and verified, deliver sequentially:

1. Fetch origin and confirm local dev still descends from the current origin/dev.

2. Push only dev:

   git push origin dev

3. Monitor the exact pushed dev SHA and require deploy_staging to succeed. Stop on any failed, canceled, skipped, or blocked job; do not push master while the staging pipeline is unfinished or unsuccessful.

4. Fetch origin again and confirm local master still descends from the current origin/master.

5. Push only master:

   git push origin master

6. Monitor the exact pushed master SHA and require deploy_production to succeed.

When only one target exists, fetch origin, confirm the local target still descends from its remote counterpart, push only that target, and verify its remote SHA plus feature-commit containment. Do not monitor its pipeline or deployment unless the user explicitly requested monitoring.

Never include the feature branch in a push refspec. Never use one atomic or multi-ref push for dev and master. If either remote target advanced, fetch, reconcile locally, rerun affected checks, then retry or report the blocker.

Verify every pushed remote target SHA and feature-commit containment after the push.

Monitor Deployments When Required

Enter this section only when the user explicitly requests deployment monitoring or both dev and master are being pushed. Otherwise stop after remote SHA and containment verification.

Use GitLab MCP to verify deployments. Resolve project_id from the origin URL; do not ask for it when it is available locally. Activate the pipelines and ci tool categories with discover_tools when their tools are not already available.

Monitor each pushed target before pushing the next one:

1. Call list_pipelines with the branch and exact SHA. Select only the pipeline for that SHA; never substitute an older successful pipeline.
2. Poll get_pipeline while the pipeline is non-terminal. Recheck at progressively longer intervals instead of rapid polling.
3. Call list_pipeline_jobs and identify the deployment job for the expected environment from its name, stage, and environment metadata. Require that exact job to finish with success; pipeline success alone is not deployment proof.
4. When GitLab exposes environment/deployment records, resolve them with list_environments and list_deployments, then confirm with get_deployment that the matching environment, branch, and SHA succeeded. If the project does not create deployment records, use the successful exact-SHA deployment job as the proof.
5. Continue until every monitored deployment succeeds. Treat failed, canceled, skipped, or blocked manual deployment jobs as unsuccessful. Do not retry, play, cancel, or otherwise mutate a pipeline unless the user explicitly requests it.

On failure, inspect the failed deployment job with get_pipeline_job or get_pipeline_job_output and report the pipeline, job, environment, SHA, status, URL, and concise failure evidence. Do not claim delivery succeeded.

Report feature commits, merge commits for existing targets, remote SHAs, checks, and final worktree state. When monitoring was required, also report each monitored pipeline/job or deployment ID, URL, and final status.