Document Scope
This document governs commit-message structure and content 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, and future <workspace-root>/<repository> repositories.
Commit messages are written for humans, future ChatGPT and Codex sessions, future AI agents, automation workers, search systems, incident recovery, and operations database ingestion. They are human-readable structured text, not a machine-only schema.
This document also governs merge commit messages. A merge commit is not a disposable Git artifact. A merge commit on main is a high-value operational record because it identifies the integrated branch, the final validated state, the merge method, the risk posture, and the cleanup that followed the branch. If a merge commit is shallow, vague, or auto-generated, it damages the future automation and repair record even when the underlying code is correct.
1. Purpose
Commit messages are not merely Git notes. They are structured operational records of why work happened, what changed, what remained stable, how safety was checked, and what work the change generated, whether repository CI/CD automation was affected, whether repository classification and governance records remain accurate, and whether supply-chain controls were triggered.
A future reader must understand the commit without the original chat transcript. Detailed messages prevent repeated investigation and temporary workarounds from quietly becoming architecture.
2. Commit Messages As Operational Database Records
Commit history is expected to become a direct input to operations database records, search indexes, retrieval systems, MCP-accessible project context, AI repair workflows, and future automation workers. The message body must therefore explain the operational intent of a change, not merely label the file edits.
Future systems may read main branch commit history to determine how a subsystem is supposed to behave, why a validator exists, why a pipeline failed, why a temporary boundary was accepted, what validation was performed, what recovery path is safe, and what follow-up task was generated. The commit message must be useful without the original chat transcript.
Consistent labels and full explanatory sentences make records extractable while preserving readability. Do not compress the record to save space. Do not replace the record with a vague title, a one-line summary, or a reference to an external conversation.
Do not invent hashes, validation, outcomes, pipeline statuses, file paths, branch names, merge request numbers, or identifiers. Use values actually observed from Git, GitLab, validation tools, terminal output, or user-provided evidence.
2.1 Authoritative Main Merge Record Rule
Branch commits are development checkpoints. They may record intermediate work, experiments, corrections, false starts, local validation, and the reasoning that existed while the branch was still a sandbox.
The merge commit on main is the authoritative operational record for the completed branch. It must describe the final result of integrating the branch into the repository state that future operators, automation workers, operations database ingestion, search systems, MCP-accessible context, and AI-agent repair workflows should treat as current.
Future automation should prefer main branch merge commits as the top-level source of branch outcome. Automation may inspect child commits for additional detail, but it must not be required to reconstruct the branch outcome from child commits when the merge commit should have stated the result directly.
The required merge-commit perspective is: what main looked like before the branch, what main became after the branch merged, what validation proves that outcome, what risks remain, what cleanup remains, and what follow-up work the integrated outcome generated.
Do not treat branch commits as a substitute for the final merge record. A branch can contain messy work-in-progress history; the merge commit must capture the clean operational truth of the final integrated state.
3. Required Commit Structure
Short imperative title
Operational summary:
Purpose:
Scope:
Files changed:
Behavior changed:
Behavior preserved:
Validation performed:
Validation not performed:
Repository classification:
Architectural impact review:
Supply-chain impact:
Repository governance review:
CI/CD impact:
Workflow weakness and safeguard review:
Generated follow-up tasks:
Cleanup remaining:
Risks and unresolved concerns:
Recovery value:
Operational database notes:
Consider every label. Use None with a short explanation when a section genuinely has no entries. Do not require or embed fake YAML inside commit messages.
4. Title Rules
Write a concise imperative title naming the durable outcome, such as Add provider-neutral summary rewrite wrapper or Split Git governance standards.
Avoid fix stuff, updates, cleanup, or changes. Avoid provider and business names unless they add necessary identification.
5. Operational Summary
Summarize the completed change and operational effect in full explanatory sentences. State whether runtime behavior changed.
6. Purpose
Explain the problem, requirement, or risk that caused the work. Distinguish the reason from the implementation.
7. Scope
Name the repository and bounded subsystem. State important exclusions, especially when production resources, secrets, databases, other repositories, or runtime behavior were untouched.
8. Files Changed
List every changed, created, deleted, or renamed file and explain its role. If the pipeline configuration file changed, identify it as high-impact repository automation. Do not hide unexpected files in a broad summary.
9. Behavior Changed
Describe externally visible, runtime, operational, validation, CI/CD pipeline, deployment, or documentation behavior that changed. For documentation-only commits, say runtime code did not change.
10. Behavior Preserved
Record compatibility contracts, fallbacks, safety boundaries, interfaces, data formats, or workflows intentionally kept stable.
11. Validation Performed
Record exact commands or named checks and outcomes. If a remote pipeline ran, record the pipeline status and relevant job result. Include important pass markers, exit codes, and no-network or no-mutation evidence. Do not write only tests passed.
12. Validation Not Performed
Name skipped checks and explain why. Distinguish out-of-scope checks from checks blocked by environment or risk.
13. Repository Classification
The Repository Classification section records the active repository class and whether the class affected validation, CI/CD, supply-chain, release, SBOM, signing, deployment, or state-record requirements.
Use clear statements such as:
Repository classification:
- Repository: <workspace-root>/app.
- Class: Class A deployable application repository.
- Classification status: confirmed for this task based on backend runtime behavior.
- Multi-class handling: not applicable.
- Effect on this commit: Class A validation, CI/CD review, supply-chain review, and repository governance review were required before commit readiness.
For context/reference repositories, state that the repository is Class C and identify whether the change affected source inventory, mirror state, update history, or license review. For the server repository, state whether the task was treated as Class E infrastructure work, Class A runtime-support work, documentation-only work inside an infrastructure repository, or multi-class work.
14. Architectural Impact Review
The Architectural Impact Review section records whether the committed change affected, required, or exposed updates beyond the immediate files edited. It must be written as a durable operational record, not as a bare checklist.
This section must address repository class, runtime behavior, validation behavior, configuration and secrets, database or persistent state, API/frontend/dashboard/customer-visible contracts, monitoring and operations records, documentation and runbooks, CI/CD, Docker, Kubernetes, deployment or infrastructure, and future AI-agent or operations database impact where relevant.
Use clear statements such as:
Architectural impact review:
- Repository class: Deployable application repository.
- Runtime behavior changed: Yes. The feed processor now loads the summary route through the shared runtime configuration path.
- Validation behavior changed: Yes. The runtime contract verifier was updated and rerun because the changed entry point affects AI summary routing.
- Configuration or secrets changed: No private configuration values changed, and no secret names were added or renamed.
- Database or persistent state changed: No schema, query, migration, or persistent data mutation changed in this commit.
- API, frontend, dashboard, or customer-visible contract changed: No customer-visible API or website contract changed.
- Monitoring, operations, reports, or AI-agent records changed: Yes. The operations note now records the selected summary route for later incident review.
- CI/CD impact: The existing validation pipeline remains appropriate because the same verifier command is still run.
- Docker impact: Docker is not yet adopted in this repository, but the changed runtime command should be considered when container startup commands are created.
- Kubernetes impact: Kubernetes is not yet adopted and no manifest work is required for this commit.
- Deployment or infrastructure impact: No deployment automation or infrastructure resource changed.
- Documentation or runbook impact: The local validation command in the relevant handoff was updated.
- Immediate fixes made before commit: The stale validation note identified during review was corrected before staging.
- Follow-up tasks generated: Add the new runtime command to the future Docker startup-command checklist when Docker is introduced.
- Reason unresolved items were deferred: Docker is not yet part of the active repository implementation, so no container file exists to update in this task.
The review must cause action before commit when safe. If the review identifies a stale command, missing validation file, inaccurate handoff, missing documentation note, missing test, or incomplete pipeline/Docker/deployment configuration that can be corrected without broadening the task improperly, correct it before the commit and record the correction. If the issue cannot be corrected safely inside the current task, record it as a generated follow-up task.
15. Supply-Chain Impact
The Supply-Chain Impact section records whether the commit introduced, removed, upgraded, downgraded, pinned, mirrored, installed, imported, copied, signed, scanned, or depended on an external artifact.
This section must be included when the change affects packages, lockfiles, container images, base images, CI/CD job images, pipeline includes, remote Git sources, copied source material, local development tools, IDE extensions, AI models, MCP servers, infrastructure modules, mirrored reference material, SBOMs, signing, or artifact records.
Use clear statements such as:
Supply-chain impact:
- External artifact changed: yes.
- Artifact type: Python package and lockfile update.
- Approval status: approved by operator before integration.
- Records updated: state/supply_chain/artifacts/example-package.md and state/integration_records/example-package.md.
- SBOM impact: release SBOM must be regenerated before the next production release.
- Cosign or signing impact: not applicable because this commit did not produce a container image.
- Follow-up required: none.
If no artifact changed, say so plainly:
Supply-chain impact:
No external artifact was introduced, removed, upgraded, downgraded, mirrored, installed, imported, copied, signed, scanned, or otherwise changed by this commit. No Supply Chain Record, Technology Decision Record, Integration Record, SBOM, or signing update was required.
Do not claim artifact approval unless the operator actually approved it. Do not hide dependency changes inside a general architecture note.
16. Repository Governance Review
The Repository Governance Review section records whether state records remained accurate after the change.
Use clear statements such as:
Repository governance review:
- Repository Classification Record impact: no change required because the repository class did not change.
- Supply Chain Record impact: no change required because no external artifact changed.
- Technology Decision Record impact: no change required because no architecture decision changed.
- Integration Record impact: updated to describe the new runtime validation command.
- Handoff or release-history impact: handoff updated with validation evidence; release history not affected.
- State folder impact: no new state folders required.
- Records reviewed but left unchanged: repository classification and supply-chain inventory remain accurate.
- Follow-up required: none.
This section prevents a commit from being technically correct while leaving durable repository records stale.
17. CI/CD Impact
The CI/CD impact section records whether the commit affects repository automation.
Include this section when the change affects pipeline configuration, dependencies, tooling, tests, build commands, deployment behavior, runtime commands, environment variables, secrets, protected variables, database migration behavior, or repository structure.
Use clear statements such as:
CI/CD impact:
- No pipeline configuration changed.
- Pipeline update needed: no.
- Expected pipeline behavior after push: existing validation pipeline should run unchanged.
- Deployment expected: no.
or:
CI/CD impact:
- Updated the repository pipeline to run the new test command.
- Expected pipeline behavior after push: lint and test jobs should run automatically.
- Deployment expected: no.
If the repository has no pipeline yet, record whether pipeline adoption is required or deferred:
CI/CD impact:
- No pipeline configuration exists yet.
- Pipeline update needed: deferred.
- Reason: this documentation-only change did not alter validation, build, or deployment behavior.
- Follow-up: none generated by this commit.
- Deployment expected: no.
Do not claim a pipeline passed unless the result was actually observed. Do not claim deployment did not occur unless that conclusion follows from the pipeline configuration, pipeline result, or task scope.
18. Workflow Weakness and Safeguard Review
Every commit and merge commit must include a separate Workflow Weakness and Safeguard Review section. This section must explicitly answer:
Has this commit revealed a weakness, ambiguity, missing safeguard, or repetitive manual step in the project standards or workflows?
This section is expected to become one of the highest-value inputs for future operations database ingestion and AI-worker improvement tasks. It must not be hidden inside Risks and unresolved concerns, Generated follow-up tasks, or Operational database notes.
If no weakness was identified, write that plainly:
Workflow weakness and safeguard review:
No workflow weakness, ambiguity, missing safeguard, or repetitive manual step was identified from this commit.
If a weakness was identified, write it in full sentences and state what happened before commit:
Workflow weakness and safeguard review:
This commit revealed that the current validation standard named the verifier command but did not explain when the command must be rerun after summary-route changes. The ambiguity matters because a future coding agent could change route behavior and commit without proving that the runtime contract still holds. The validation standard was updated before this commit to require the verifier when summary routing changes. No separate follow-up remains for this weakness.
If the issue cannot be fixed before commit, the section must say why and must connect the issue to a generated follow-up task:
Workflow weakness and safeguard review:
This commit revealed that Docker startup-command validation will need a repository standard once Docker is adopted. The issue cannot be fixed in this commit because the repository does not yet contain Docker configuration and the current task did not authorize containerization work. A generated follow-up task records that the future Docker adoption task must define startup-command, environment-variable, health-check, and validation expectations.
The assistant or coding agent must always ask whether the weakness can be remediated before commit. The default is to remediate immediately when the remediation is inside scope, low risk, validated, and does not mix unrelated work into the checkpoint.
19. Generated Follow-Up Tasks
Generated follow-up tasks are tasks created because the committed task happened. They are not ordinary roadmap items that already existed.
The grocery analogy is useful: grocery shopping includes bringing home and unpacking groceries. The resulting bags, cardboard, trash, and cleanup are generated follow-up work. Technical changes have the same pattern. A documentation conversion can create old-document retirement work. A routing patch can create configuration examples to revise. A verifier improvement can expose untested runtime behavior. A merge can reveal commit-message tooling gaps.
Each generated follow-up task must identify:
- What task was generated.
- What caused it.
- Where it exists.
- Why it matters.
- What should happen next.
- Whether it is blocking, near-term, deferred, or optional.
Write tasks clearly enough for a future AI agent or operations database to extract, catalog, prioritize, and act on them.
Generated follow-up tasks:
- Near-term: Update the app repository configuration example to document the new summary routing keys. The routing patch created shared endpoint selection in scripts/jh_summary_poster.py, but the safe example does not show the route. This matters because operators can miss the capability. Update and validate the example in a separately scoped task.
Do not relabel pre-existing backlog work as generated merely because the task exposed it.
20. Cleanup Remaining
Record disposable helpers, temporary branches, superseded documents, stale examples, or other cleanup still required. State where each item is and when removal is safe.
21. Risks and Unresolved Concerns
This section is not a vague dumping ground. Record every risk, temporary workaround, migration concern, naming debt, vendor-lock concern, validation gap, ambiguity, and generated task in full explanatory sentences.
Explain what created the risk, why it matters, where it exists, and what must happen next. Do not bury material risk in catchall language.
22. Temporary Solution Rule
A temporary solution is allowed only when explicitly identified as temporary, necessary for the current task, and recorded with a required follow-up.
If it creates cleanup, migration, refactoring, vendor lock-in, naming debt, or ambiguity, remediate before the next task when possible. Otherwise record location, cause, consequence, next action, and priority. A temporary solution must not quietly become architecture.
23. Recovery Value
Explain how the commit supports recovery. Identify the state restored by reverting it, compatibility a corrective patch must preserve, or evidence a responder should inspect.
Git reversal does not undo external side effects such as database mutations, messages, cloud objects, scheduler changes, pipeline artifacts, deployment jobs, or remote environment changes. State separate recovery requirements.
24. Operational Database Notes
Useful human-readable fields include:
tags:
related task:
related handoff:
related verifier:
related pipeline:
affected subsystem:
follow-up class:
risk class:
cleanup class:
commit type:
These labels are not fake YAML. Use stable, vendor-neutral terms where possible.
25. Merge Commit Message Requirements
A merge commit must meet the same operational-message standard as an ordinary commit. It must explain the integrated branch or task, the resulting operational state, the validation completed on the source branch, the validation expected after merge, generated follow-up tasks, cleanup remaining, unresolved risks, and recovery value.
A merge commit is especially important because future automation may ingest main branch history and use the merge commit as the top-level record for a completed branch. The branch commits may preserve detail, but the final merge commit must still tell the integrated story. Do not rely on a future reader, future AI agent, automation worker, operations database process, or search system to open every child commit to reconstruct what the merge meant.
A compliant merge commit must include, at minimum:
Short merge title
Operational summary:
Purpose:
Scope:
Files merged:
Behavior changed:
Behavior preserved:
Validation performed:
Validation not performed:
Architectural impact review:
CI/CD impact:
Workflow weakness and safeguard review:
Generated follow-up tasks:
Cleanup remaining:
Risks and unresolved concerns:
Recovery value:
Operational database notes:
The merge message must identify the source branch, target branch, repository path, repository class, relevant pipeline result, whether deployment was expected, whether production mutation occurred, and whether branch cleanup remains.
Do not use a merge workflow that produces an uncontrolled shallow message such as:
Merge branch 'feature-name' into 'main'
That form is insufficient by itself. It may appear in GitLab-generated merge commits, but it does not satisfy this standard unless the body also contains the full operational record.
The GitLab web interface may prepopulate merge request descriptions from commit messages or branch metadata, but the default GitLab UI merge action may still create a shallow merge commit message. Do not assume that a detailed merge request description will become the final merge commit body.
Before pushing main, verify the actual merge commit body:
git show --no-patch --format=full HEAD
If the merge commit body is defective and main has not been pushed, amend the merge commit message before pushing:
git commit --amend
git show --no-patch --format=full HEAD
A defective unpushed commit message must be repaired before push. A defective pushed commit on protected main must not be rewritten unless the user explicitly orders that higher-risk action. Repair it forward with a corrective documentation or audit commit.
Approved merge methods when merge-message detail matters are:
- A local Git merge from PowerShell with an explicit full merge commit message.
- GitLab CLI automation with an explicit merge commit message.
- GitLab API automation with an explicit
merge_commit_message.
The GitLab UI is acceptable for reviewing pipeline status and merge request context. It is not the preferred final merge mechanism when it cannot guarantee the required merge commit message body.
Follow protected-main rules in docs/git-checkpoint-standard.md.
26. Commit Message Verification Before Push
Before pushing a commit or merge commit that is intended to become part of main, verify the recorded message body, not merely the command that created it. The required inspection command is:
git show --no-patch --format=full HEAD
The verification must confirm that the title and body are intact, that no pasted text was truncated or corrupted, that all required sections are present, and that any claims about validation or pipeline results match observed facts. If the message is wrong and the commit has not been pushed, amend it before push.
Do not move forward merely because Git accepted the commit. Git accepting a commit proves only that an object was created. It does not prove that the commit message is complete, accurate, or useful for operations database ingestion.
27. Corrective Commit Message Requirements
A corrective commit must identify the prior defect, explain why a new commit is used instead of history rewriting, describe the correction, and record remaining recovery action. Reference a commit hash only after reading it from Git.
28. Documentation-Only Commit Requirements
Identify guidance added, migrated, superseded, or retired; state that runtime behavior was unchanged; and record structural validation, link checks where applicable, git diff --check, and status review.
29. Code Commit Requirements
Describe runtime behavior changed and preserved, compatibility contracts, configuration and data effects, targeted tests, and checks not run. Include rollback consequences when external state may have changed.
30. Verifier Commit Requirements
Identify the contract enforced, fake-call or no-network guarantees, expected pass markers, and whether production code was unchanged. Record behavior exposed but not covered as generated follow-up work.
31. Context-Repository Update Commit Requirements
For a context, inventory, handoff, or knowledge repository, identify source observations, freshness date, repository boundaries, superseded records, and intended consumers. Do not imply that context updates changed application runtime.
32. Vendor-Neutral and Business-Name-Agnostic Wording
Use vendor-neutral and business-name-agnostic wording where precise. Prefer AI provider, object storage, email delivery provider, or the active repository when the contract is general.
Retain specific names when identifying a real compatibility alias, endpoint, repository, incident, or migration constraint.
33. Examples
Split Git governance standards
Operational summary:
Separated Git checkpoint mechanics from commit-message requirements and retired the combined standard. Runtime behavior was not changed.
Purpose:
Reduce topic overlap while preserving complete safety and history guidance.
Scope:
Documentation and state handoff files in the active repository only.
Files changed:
Created two focused standards, deleted the superseded combined file, and added the task handoff.
Behavior changed:
Operators now use separate standards for checkpoint workflow and commit content.
Behavior preserved:
Branch-first work, stable main, path-specific staging, recovery rules, and detailed operational messages remain required.
Validation performed:
Required files and phrases were found; the old file was absent; git diff --check passed.
Validation not performed:
No runtime checks were run because no runtime code changed.
CI/CD impact:
No pipeline configuration changed. No deployment job was expected.
Generated follow-up tasks:
None identified during this scoped refactor.
Cleanup remaining:
None.
Risks and unresolved concerns:
External links to the retired filename may require later discovery; no such links were changed outside this task scope.
Recovery value:
Reverting restores the combined document and removes the focused replacements.
Operational database notes:
tags: git, governance, documentation
affected subsystem: repository workflow
commit type: documentation
Enforce summary secret fallback precedence
Operational summary:
Expanded deterministic runtime-contract coverage without changing production behavior.
Purpose:
Prevent routing work from breaking established summary-specific and legacy aliases.
Scope:
Runtime verifier and handoff only; no live provider, messaging, database, or production calls.
Files changed:
Updated the verifier and added its state handoff.
Behavior changed:
The verifier now rejects precedence and endpoint-shape regressions.
Behavior preserved:
Production summary code and provider delegation remain unchanged.
Validation performed:
The verifier returned its pass marker with zero network calls, posts, and database mutations.
Validation not performed:
Live integration tests were intentionally not run.
CI/CD impact:
No pipeline configuration changed. No deployment job was expected.
Generated follow-up tasks:
- Deferred: Add equivalent coverage for configuration-selected endpoint fallback if shared routing is introduced. The expanded secret contract generated this need in the summary routing verifier because a second resolution path would otherwise remain unprotected.
Cleanup remaining:
None.
Risks and unresolved concerns:
The verifier proves deterministic contracts but not live provider availability.
Recovery value:
Reverting removes verifier coverage only.
Operational database notes:
tags: verifier, AI-routing, compatibility
follow-up class: test coverage
risk class: integration availability
commit type: verifier