Skip to the content.

Git and Promotion

Overview

Git behavior in CLike is currently extension-first and promotion-aware.

This means:

Current extension commands

Git-related commands contributed by the extension:

Current settings

All automation is off by default (since the 2026-10 hardening). Machine-scoped settings are read by VS Code only from User settings (an opened project cannot turn on commits or pushes): a value in the project’s .vscode/settings.json is ignored, and CLike warns about it with Apply in User settings.

Setting Default Meaning
clike.git.autoCommit false Commit the files produced by each Harper phase — only those files (machine-scoped)
clike.git.autoPush false Push phase commits, tags and gate merges (machine-scoped)
clike.git.gitMergeOnGate false After a PASS gate, merge the REQ branch into the default branch (--no-ff)
clike.git.openPR false Open a PR on /finalize
clike.git.pushRebase false Rebase the REQ branch on the remote default branch when the tree is clean

Other settings: gitDeleteBranchOnMerge, gitReturnToFeatureAfterMerge, remoteUrl, commitMessage, remote, defaultBranch, conventionalCommits, branchPrefix, tagPrefix, prPerReqDraft.enabled, prPerReqDraft.useGhCli, prBodyPath.

Phase sync guarantees (clikeGitSync)

Current phase relationship

The inspected codebase and reference docs support this phase-aware model:

Candidate-first promotion

Promotion is not direct generation into canonical roots.

The current sources justify documenting this rule:

This separation is important for:

Gate auto-merge promotion (default)

On a passing /gate (PASS, PASS_WITH_WARNINGS with accepted warnings, or an audited override) the REQ is promoted without prompts (clike.gate.autoPromote, default merge; extensions/vscode/promote-merge.js):

Three ways to choose it: the setting clike.gate.autoPromote (merge default: no prompt; ask: the strategy list, with auto-merge first, then folder / suffix / backup / skip / overwrite; off: no promotion), or for one run /gate <REQ> --auto-merge, --ask, --no-promote.

Repository-root deliverables (runs/kit/<REQ>/root/)

Some REQs deliver files outside src/ and test/: run and setup scripts, deployment scripts, infrastructure, root manifests. The KIT writes them under runs/kit/<REQ>/root/<repository path> (for example runs/kit/REQ-033/root/deploy/aws/01_inventory.sh) and the gate promotes them to <repository path> with the same 3-way merge, report and conflict files.

REQ branches

Each REQ’s phases are committed on feature/req-<n>. A new REQ branch starts from the default branch when the current work is merged into it, otherwise it is stacked on the current branch (merge-on-gate off: REQ-004 carries the REQ-003 commits it depends on). A phase that cannot be committed (switch refused, commit error) shows a warning instead of failing silently.

Promotion helpers

The extension contains promotion-oriented helpers and manifests, including references to:

Promotion should therefore be documented as:

Current merge behavior

The settings indicate support for merge-on-gate behavior:

Merge is opt-in (default false) and happens only after a PASS gate that promoted the REQ. With autoPush and a remote, CLike first fetches and merges <remote>/<default> into the default branch (a PR merged on the host), then merges the REQ (--no-ff) and pushes; a conflict, a failed switch or a failed push is shown as a warning with its cause and the commands to run.

Current branch conventions

The sources and attached docs show multiple naming patterns in different places, including:

Because both conventions appear in the inspected material, official docs should avoid overstating a single universal branch scheme unless the repository later consolidates it.

Recommended current wording:

PR integration

Current settings and docs reference:

This supports documenting PR flows as:

Safety guarantees to keep explicit

The current sources justify making these rules explicit: