truthmark/docs/standards/versioning.md

---
status: active
doc_type: standard
last_reviewed: 2026-05-16
source_of_truth:
  - ../../package.json
  - ../../package-lock.json
  - change-notes.md
  - https://semver.org/
---

# Versioning

## Trigger

Use this standard only when a task changes or asks whether to change:

- `package.json` version
- root package entries in `package-lock.json`
- release/version policy
- a `changes/` note with `Version action: patch`, `minor`, or `major`

Do not load this standard for ordinary docs, workflow text, generated-surface, or code changes unless a package version decision is in scope.

## Goal

Choose Truthmark's own package version using Semantic Versioning 2.0.0. Normal committed versions use `MAJOR.MINOR.PATCH`.

`package.json` is the maintained version source. `package-lock.json` follows it. Generated workflow surfaces are refreshed by rendered-content comparison plus `truthmark init`; they do not carry package-version freshness markers.

This is an internal repository maintenance standard. It is not a user-facing feature, installed workflow feature, or generated workflow capability.

## First Gate

If the change does not alter published package behavior, do not bump the package version.

No bump examples:

- internal standards for this repository
- agent routing guidance for maintainers
- documentation corrections with no published behavior change
- tests, refactors, formatting, or cleanup with no published behavior change

## Decision Table

| Change                                                                                                                                                   | Version action                                |
| -------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- |
| Backward-incompatible public API or shipped workflow change                                                                                              | `MAJOR + 1`, reset `MINOR` and `PATCH` to `0` |
| Backward-compatible public API addition, generated-surface capability, shipped workflow capability, deprecation, or substantial user-visible improvement | `MINOR + 1`, reset `PATCH` to `0`             |
| Backward-compatible bug fix, diagnostic correction, packaging fix, or published documentation correction                                                 | `PATCH + 1`                                   |
| Internal-only maintenance with no published package behavior change                                                                                      | no version change                             |

Do not use prerelease or build metadata in the committed package version unless the release task explicitly asks for it.

## Public API For Bump Decisions

Treat these as published package behavior:

- CLI command names, options, exit behavior, result envelopes, and diagnostics contracts
- `.truthmark/config.yml` schema and hierarchy behavior
- generated instruction blocks, skill metadata, prompt files, helper manifests, and managed refresh markers produced by the package
- installed workflow boundaries, trigger contracts, report shapes, and completion gates as shipped package behavior
- runtime compatibility and npm package contents

## Version Change Procedure

Before changing a version number:

1. Identify the previous released version from the latest lower `release/<version>` tag.
2. Inspect all pending release payload since that previous version: committed branch diff plus staged, unstaged, and untracked files that will ship.
3. Classify the payload with the decision table above before editing `package.json`.
4. If the requested new version is lower than the required bump, block the edit and report the required version. Do not accept a patch request for a minor or major payload.

When changing a version number:

1. State the previous version, requested version, required bump class, and SemVer rationale in the handoff, PR, or release note.
2. Create or update the matching `changes/` note from [change-notes.md](change-notes.md), covering the full release payload since the previous version.
3. Update `package.json` and the root package entries in `package-lock.json` together.
4. Rerun `truthmark init` when generated surfaces need refresh, then inspect the generated-surface diffs. Generated surfaces use managed/stale-surface wording instead of package-version freshness markers; helper manifests name the runner and command shape without pinning the package version.
5. Run the focused verification required by [testing-and-verification.md](testing-and-verification.md). For release-sensitive package version changes, `npm run release:check` is the default final gate.

## Agent Output

When reporting a package version decision, state only:

- chosen version action
- one-line SemVer rationale
- whether the requested version matched the required bump
- files changed or intentionally left unchanged
- matching change note path when a version changes
- verification run or explicitly skipped