Version Control

Use this document as the standard version-control rule set for Codex-assisted projects.

Version Format

Use Semantic Versioning:

MAJOR.MINOR.PATCH

Example:

1.4.1

Display versions may include a leading v, for example v1.4.1. Stored variables should omit the leading v, for example "1.4.1".

Version Rules

1. MAJOR increments only with Robert's explicit approval.
2. MINOR increments for backwards-compatible new features.
3. PATCH increments for backwards-compatible bug fixes, documentation updates, test harnesses, prompt fixes, script fixes, or small safe corrections.
4. When MAJOR increments, reset MINOR and PATCH to zero.
5. When MINOR increments, reset PATCH to zero.
6. Released versions are immutable. Once a version is released, do not change that exact version; create a new version.
7. New tracked modules should normally start at 1.0.0 unless Robert says the project is pre-release.
8. Significant work, an explicitly requested handover, or a meaningful push/delivery should update versions for the modules included in that logical body of work.

During Active Development

Do not bump versions or create archive copies for every normal in-session edit.

During ordinary development, Codex should:

• edit the active files directly;
• verify the change;
• avoid archive copies;
• avoid version bumps.

Version bumps and archive copies happen only when:

• Robert explicitly asks for a version/archive update or handover;
• a significant change is ready to be recorded; or
• a meaningful push/delivery is being prepared.

This keeps active work lightweight while still preserving release/handover checkpoints.

What Counts As A Module

A module is any separately maintained project file or component, including:

• application/backend code files;
• frontend/UI code files;
• scripts;
• prompts;
• config templates where behaviour changes;
• documentation templates where project process changes.

If a file can be edited independently and has meaningful behaviour or process impact, treat it as version-controlled.

Authoritative Version Location

Each version-controlled file should contain its own authoritative version near the top.

For code files, use a variable where practical:

MODULE_VERSION = "1.0.0"

For scripts, use the same style when the language supports it:

SCRIPT_VERSION = "1.0.0"

For prompt files, use a visible header comment or metadata block at the top:

#Prompt: stewards_prompt
#Version: 1.0.0
#Last updated: YYYY-MM-DD

For plain text files where # is not appropriate, use:

Version: 1.0.0
Last updated: YYYY-MM-DD

Avoid duplicated version numbers. If a UI displays a version, it should display the version from the module variable rather than hard-coded template text.

Active Filename Rule

The active user-facing filename should stay stable.

Examples:

prompts\stewards_prompt.txt
scripts\build_report.py

Do not rename the active file just because the version changes. Versioned copies belong in an archive folder.

Archive Rule

After significant work, for an explicitly requested handover, before a meaningful push/delivery, or when Robert explicitly asks for a version/archive update, copy the previous version of each changed version-controlled file into an archive folder under the appropriate parent folder.

Examples:

prompts\archive\stewards_prompt_v1.0.0.txt
scripts\archive\build_report_v1.0.0.py
documents\archive\README_v1.0.0.md

Then update or confirm the active file in place and bump the version inside the active file.

If the active file is:

prompts\stewards_prompt.txt

then the current file remains:

prompts\stewards_prompt.txt

and the previous version is stored as:

prompts\archive\stewards_prompt_vX.Y.Z.txt

Use the version being archived in the archive filename, not the new version.

Changelog And Handover

After significant work, for an explicitly requested handover, or before a meaningful push/delivery:

• update the changelog with the new version;
• update the handover with the current active version;
• list changed modules/scripts/prompts and their versions;
• record verification commands and outcomes;
• note any archived files created.

Scripts And Prompts

Scripts and prompts must be controlled by version rules because they can materially change outputs.

When creating a new script or prompt:

• add the version header immediately;
• start at 1.0.0 unless Robert says otherwise;
• document its purpose in one or two lines near the top.

When changing an existing script or prompt:

• during active development, edit and verify without archive/version churn;
• after significant work, for a requested handover, before a meaningful push/delivery, or when Robert asks, archive the old version;
• keep the active filename unchanged;
• bump MINOR for new capability;
• bump PATCH for wording fixes, parameter tweaks, small logic fixes, or test-only changes;
• update any related changelog/handover at the applicable significant-work, handover, or push checkpoint.

UI Display Rule

All UI modules should display their version number where practical:

• bottom-right is preferred;
• top-right is acceptable if the layout requires it;
• the displayed value must come from the authoritative module/app version variable.