mirror of
https://github.com/merlinhu1/truthmark.git
synced 2026-08-25 07:53:25 +02:00
fb2c469005
* feat: add Truth Sync intent checklist * feat: add canonical agent workflow package Add the .truthmark/agent canonical workflow package, convert duplicated host workflow bodies into adapter/expanded-adapter surfaces, and validate canonical/adapter freshness in Truthmark check. Refresh generated surfaces and package metadata for Truthmark 2.3.0, with OpenSpec tasks completed and release notes added. * fix: preserve native workflow skill packages * docs: record native skill package decision * fix: drop unused agent workflow package * chore: remove implemented OpenSpec docs * chore: release workflow fixes as 2.2.2 * fix: remove agent-visible version markers * fix: drop generated surface version markers * feat: capture decision context in Truth Sync --------- Co-authored-by: MerlinH <merlinh221@gmail.com>
92 lines
5.0 KiB
Markdown
92 lines
5.0 KiB
Markdown
---
|
|
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
|