Document Scope
This document governs Git as a safety system, CI/CD-aware recovery checkpoint workflow, and repository state-control process for the active repository named in a task. It applies across the modular workspace, including <workspace-root>/app, <workspace-root>/site, <workspace-root>/admin, <workspace-root>/server, ctx-* context/reference repositories, personal utility repositories, and future repositories represented by <workspace-root>/<repository>.
Each repository is independent. This standard does not authorize cross-repository staging, commits, pushes, or cleanup.
1. Purpose
Git must preserve understandable, verified recovery points. A commit is ready only when the repository state is understood and validated enough to recover to; saving files is not sufficient.
This standard defines branch-first work, repository preflight, staging, checkpoint readiness, Architectural Impact Review, pushing, pipeline-status review, merging, recovery, and branch cleanup. Detailed commit content is governed separately by 15-git-commit-message-standard.md.
2. Branch-First Workflow
main is the stable recovery line. Ordinary fixes, refactors, documentation changes, verifier work, migrations, and operational changes belong on a named branch. Do not work directly on main unless the user explicitly approves an emergency exception.
Branch names should describe the work. Merge into main only after validation, complete handoff records, detailed commits, required pushes, review, and user approval.
3. Repository Preflight
Start at the named repository root:
cd <workspace-root>/<repository>
git status --short
git branch --show-current
git log --oneline -5
Stop before editing when the branch is unexpected. Inspect unexpected dirty files and preserve unrelated user work. Do not infer that a commit is known-good from memory. Do not infer that the remote repository will validate the branch unless the repository pipeline status has been reviewed or the repository has no configured pipeline.
git show --stat HEAD
git show --name-only HEAD
git diff -- path\to\file
git diff --cached -- path\to\file
git diff --function-context -- path\to\file
4. Staging Discipline
Staging is a deliberate selection step. Use path-specific staging and inspect the result:
git status --short
git add -- path\to\intended-file.py path\to\intended-doc.md
git status --short
git diff --cached --stat
git diff --cached --check
git diff --cached
Do not broadly stage a dirty repository. Never stage secrets, private configuration, logs, caches, virtual environments, local databases, dependencies, or disposable scratch files unless the task explicitly approves the exact file.
Common exclusions include:
config/config.txt
config/secrets.txt
secrets.txt
logs/
tmp/
.venv/
__pycache__/
.pytest_cache/
*.sqlite
*.db
5. Commit Readiness
A commit is a verified checkpoint. Validation must match the change and its risk. Syntax checks alone are insufficient when runtime behavior, data state, external delivery, or infrastructure changed.
Before committing, confirm that required validation passed or skipped checks are justified, changed and staged files match scope, git diff --cached --check passes, the staged diff is understood, required Codex handoffs agree with the patch, and the message follows 15-git-commit-message-standard.md.
For feed processor or AI work in <workspace-root>/app, a targeted runtime contract verifier may be required. This is an app-repository example, not a universal command.
6. Repository Classification Before Commit
Before commit readiness, confirm the repository class under the Repository Classification Standard. Record whether the repository is Class A, Class B, Class C, Class D, Class E, Class F, Class G, or multi-class. If classification is uncertain, the checkpoint is not ready.
Repository classification determines validation depth, CI/CD expectations, supply-chain record requirements, release history, state-directory expectations, SBOM requirements, Cosign requirements, and whether deployment or infrastructure mutation may be in scope.
7. Architectural Impact Review Before Commit
Repository work must include an Architectural Impact Review before commit readiness. The previous CI/CD Pipeline Impact Review is now treated as one required subsection of this broader review.
Before recommending a commit, first classify the repository:
deployable application repository,
server/infrastructure repository,
context/reference repository,
personal utility repository,
other.
Then review whether the completed work affects or exposes required changes to dependencies, tooling configuration, test commands, lint or format commands, package layout, script entry points, runtime commands, build steps, frontend build behavior, deployment behavior, database migration behavior, environment variables, secrets or protected variables, documentation structure, reference-library structure, repository structure, validation commands, monitoring behavior, operations records, Docker configuration, Kubernetes configuration, backup and recovery procedures, security assumptions, public output quality, or repository automation.
The review is not merely a question-answer record. If the review identifies an issue that can be safely fixed before commit, the assistant or coding agent must fix it and validate the fix before commit readiness. If the issue is outside the approved scope, risky, production-adjacent, or better handled separately, it must be recorded as a generated follow-up task with enough detail for future recovery, operations database ingestion, and AI-worker action.
Use this compact review format before commit readiness:
Architectural impact review:
- Repository class:
- Runtime behavior changed: yes/no.
- Validation behavior changed: yes/no.
- Configuration or secrets changed: yes/no.
- Database or persistent state changed: yes/no.
- API, frontend, dashboard, or customer-visible contract changed: yes/no.
- Monitoring, operations, reports, or AI-agent records changed: yes/no.
- CI/CD impact: yes/no.
- Docker impact: not adopted/no/yes/follow-up.
- Kubernetes impact: not adopted/no/yes/follow-up.
- Deployment or infrastructure impact: yes/no.
- Documentation or runbook impact: yes/no.
- Immediate fixes made before commit:
- Follow-up tasks generated:
- Reason unresolved items were deferred:
7.1 CI/CD Subsection
For CI/CD, ask whether the change affects dependencies, tooling configuration, test commands, lint or format commands, package layout, script entry points, runtime commands, build steps, frontend build behavior, deployment behavior, database migration behavior, environment variables, secrets or protected variables, documentation structure, reference-library structure, pipeline configuration, or repository structure.
If any of these changed, determine whether the repository pipeline configuration should be created or updated.
Use this CI/CD subsection format:
CI/CD impact:
- Pipeline file changed: yes/no.
- Pipeline update needed: yes/no/deferred.
- Reason:
- Expected pipeline behavior after push:
- Deployment expected: yes/no.
If the repository has no pipeline yet, say whether a minimal validation pipeline should be created as a follow-up. Do not treat absence of a pipeline as a reason to ignore pipeline impact.
Context/reference repositories using the ctx-* prefix should normally have minimal documentation/reference validation only and no deployment. If a context/reference repository appears to need deployment, stop and reclassify the repository before proceeding.
Pipeline configuration is high-impact repository code. It can run commands, consume secrets, publish artifacts, deploy services, modify infrastructure, run database migration commands, or mutate environments. Do not edit pipeline configuration unless the task explicitly scopes that work.
7.2 Supply Chain Impact Subsection
Every repository checkpoint must consider supply-chain impact. Ask whether the change introduced, removed, upgraded, downgraded, pinned, mirrored, imported, installed, copied, signed, scanned, or depended on an external artifact.
Use this subsection format:
Supply-chain impact:
- External artifact changed: yes/no.
- Artifact type: package/container image/remote Git source/CI/CD component/AI model/MCP server/local tool/context source/other/not applicable.
- Approval status: approved/rejected/deferred/experimental-only/not applicable.
- Records updated: Technology Decision Record/Supply Chain Record/Integration Record/SBOM/release record/none required.
- SBOM impact: yes/no/not applicable.
- Cosign or signing impact: yes/no/not applicable.
- Follow-up required:
If an artifact changed and the approval status is unknown, the checkpoint is not ready.
7.3 Repository Governance Review Subsection
Before commit readiness, review whether repository governance records remain accurate. This review is separate from runtime validation.
Use this subsection format:
Repository governance review:
- Repository Classification Record impact:
- Supply Chain Record impact:
- Technology Decision Record impact:
- Integration Record impact:
- Handoff or release-history impact:
- State folder impact:
- Records updated before commit:
- Records reviewed but left unchanged:
- Follow-up required:
If a record can be updated safely inside the current task scope, update it before commit. If a record requires operator approval or a separate task, record a structured follow-up.
7.4 Workflow Weakness and Safeguard Subsection
Every commit must explicitly answer this question before commit readiness:
Has this commit revealed a weakness, ambiguity, missing safeguard, or repetitive manual step in the project standards or workflows?
If the answer is yes, determine whether the weakness can be safely remediated before commit. If it can, remediate and validate it. If it cannot, record it as a generated follow-up task with the cause, location, operational importance, and next action. This subsection must appear in the detailed commit message and merge commit message because it is expected to be valuable to future operations database ingestion and AI-worker improvement tasks.
8. Do-Not-Commit Conditions
Do not commit when unexpected files are present, required validation failed, Architectural Impact Review is incomplete, runtime or database state is unexplained, production mutation lacks approval and documentation, private or generated files are candidates, Codex changes are unreviewed, a required handoff is missing, or the change cannot be explained.
Do not hide failures with cleanup. Resolve them or record why the checkpoint is not ready.
9. Push Rules And Failures
Push the current branch unless the task names another destination:
$Branch = git branch --show-current
git push origin $Branch
If SSH, authentication, or remote access fails after a commit, do not recommit. Inspect the branch and remotes, repair the push path, and push the existing commit.
git branch --show-current
git remote -v
ssh -T git@configured-host
git push origin $Branch
A successful push does not by itself establish merge readiness.
If the repository has a configured CI/CD pipeline, review the pipeline result after pushing. A pushed branch is not remotely validated until the expected pipeline jobs have passed or the failure is understood and documented. Confirm whether deployment jobs were triggered or are waiting for manual approval. For context/reference repositories, confirm that no deployment job ran or became pending.
10. Merge Readiness
A merge is not ready merely because a branch compiles, a local diff looks correct, or the GitLab web page offers a merge button. A merge is ready only when the source branch has been validated, the expected post-merge state is understood, the merge method has been chosen, and the final merge commit message can be controlled.
For work whose commit history will be used by the operations database or future AI-agent repair workflows, the merge method is part of the task. Do not treat it as a Git hosting convenience. A default web-host merge can create an insufficient top-level commit record even when the underlying branch commits are detailed.
A branch is merge-ready only when work is complete, local validation passed, repository class has been identified, CI/CD pipeline impact has been reviewed, expected remote pipeline validation passed or is documented as unavailable/deferred, the working tree is clean, commits and handoffs tell the same story, the branch was pushed when required, and known risks are recorded.
git status --short
git branch --show-current
git log --oneline -5
git diff main...HEAD --stat
The user approves the merge. Do not merge merely because one narrow check passed.
When a full merge-level operational record is required, use one of these methods:
- Local Git merge from PowerShell with an explicit full merge commit message.
- GitLab CLI merge with an explicit merge commit message.
- GitLab API merge with an explicit
merge_commit_message.
Do not use the GitLab UI default merge action as the final merge mechanism when it cannot guarantee the required merge commit body. A detailed merge request description is not enough. The final Git object must contain the required message.
11. Merge Commit Body Verification
Before pushing main, inspect the complete merge commit body. This step is mandatory for every merge into main when the project expects commit history to become operations database input. The check must be performed even if the merge command appeared to succeed and even if the branch pipeline passed.
Inspect the body with:
git show --no-patch --format=full HEAD
git status --short
git branch --show-current
Confirm that it identifies the integrated task, source branch, target branch, repository class, operational effect, files merged, validation performed, validation not performed, CI/CD impact, deployment expectation, generated follow-up tasks, cleanup remaining, risks, and recovery value. A merge tool's successful exit does not prove the intended body was recorded.
If the body is incomplete, corrupted, truncated, or generic and main has not been pushed, amend the merge commit message before pushing. Use explicit user approval before amending if the assistant is controlling the command sequence.
If protected main has already been pushed or policy forbids rewriting, do not force push. Add a corrective documentation or audit commit that records the missing context and references the defective merge. The corrective commit must be pushed through the normal branch, pipeline, merge, and verification process.
12. Corrective Commits On Protected Main
Protected main is not rewritten to improve history. Use a corrective commit when a pushed merge contains incomplete metadata, a documentation error, or another issue that can be repaired forward.
The corrective message must follow 15-git-commit-message-standard.md, identify the defect, explain why history was not rewritten, record the correction, and preserve the relationship to the original commit. Never use force push on protected main.
13. Recovery Rules
Recovery begins with inspection:
git status --short
git diff --stat
git diff
git log --oneline -10
For uncommitted work, patch forward when the fix is narrow and clear. Otherwise use path-specific restore only after confirming what will be lost.
git diff -- path\to\file.py
git restore -- path\to\file.py
For committed or pushed defects, prefer a corrective commit or git revert. Do not rewrite pushed history without explicit instruction. Avoid git reset --hard.
Before risky experiments, use a branch, verified checkpoint, or identified stash:
git stash push -m "WIP before experiment"
git stash list
git stash apply
git switch -c experiment/descriptive-name
Git recovery does not reverse database rows, messages, cloud objects, scheduler state, or external side effects. Those require separate inspection and repair.
14. Bad Patch Handling
Inspect an uncommitted bad patch with git diff. Patch forward when safe; otherwise restore only named files and preserve unrelated work.
Fix a committed but unpushed bad patch with a corrective commit unless the user explicitly approves rewriting. Fix a pushed bad patch with git revert or a corrective commit. Prefer readable operational history over concealing mistakes.
15. Runtime Validation and Codex Handoffs
Runtime validation and Architectural Impact Review determine whether a state is safe enough to checkpoint. Follow 09-runtime-validation-standard.md and record exact output and skipped checks.
Codex implementation work requires a repo-local state handoff when the repository has a state directory or the task approves creating one. The handoff identifies scope, files, behavior, validation, skipped checks, risks, and final status. It supplements Git history; it does not replace a complete commit message. When CI/CD is relevant, the handoff must record repository class, whether a pipeline exists, whether pipeline configuration changed, expected pipeline behavior after push, actual pipeline result if pushed, whether deployment was expected, and any follow-up CI/CD work.
16. Relationship to tmp/ and state/
Repo-local tmp is disposable scratch space. Do not stage patch helpers, one-off logs, or temporary verification output. Remove them only after needed evidence is preserved.
Repo-local state is durable handoff and inventory space. Do not delete state records because a task ended. Retire them only when obsolete, intentionally superseded, or consolidated according to repository policy.
17. Branch Cleanup After Merge
After the merge is verified, pushed, and the expected main-branch pipeline result has been reviewed, confirm main is clean and contains the expected merge. Delete a work branch only after confirming it is merged and no unique work remains:
git switch main
git pull --ff-only
git branch --merged
git push origin --delete branch-name
git branch -d branch-name
Remote branch deletion is appropriate when the branch was merged, the main pipeline passed, and the task included branch cleanup. When branch cleanup was not already part of the task, ask for user approval before deleting the remote branch. Never use -D merely to bypass an unmerged warning.
18. Future AI Session Instruction Block
You are working in a named repository inside the modular workspace. Confirm the repository path, branch, and working-tree state before editing, staging, committing, pushing, merging, cleaning branches, or recommending recovery.
Use branch-first workflow and treat main as the stable recovery line. Do not perform ordinary work directly on main. Treat repository classification, supply-chain impact review, repository governance review, and Architectural Impact Review as part of commit readiness for repository work.
Run:
cd <workspace-root>/<repository>
git status --short
git branch --show-current
git log --oneline -5
Use path-specific staging and inspect the staged diff. A commit must be a verified recovery checkpoint, must include repository classification, supply-chain impact review, repository governance review, Architectural Impact Review, and CI/CD impact where relevant, and must follow 15-git-commit-message-standard.md. Codex work requires the approved repo-local state handoff.
Push the existing commit after resolving SSH or authentication failures; do not recommit. Before pushing main after a merge, inspect the full merge body with:
git show --no-patch --format=full HEAD
After pushing a branch with a configured pipeline, review pipeline status before treating the remote branch as validated. For `ctx-*` repositories, expect minimal documentation/reference validation and no deployment. Never force push protected main. Prefer corrective commits or git revert for pushed defects. Inspect before restore and avoid git reset --hard unless explicitly approved.