1.3.0 clis and index (#4)

docs/standards/change-notes.md

@@ -0,0 +1,76 @@
+---
+status: active
+doc_type: standard
+last_reviewed: 2026-05-16
+source_of_truth:
+  - versioning.md
+  - pre-completion-checklist.md
+---
+
+# Change Notes
+
+## Trigger
+
+Use this standard when a change needs PR text, release text, or a package version decision.
+
+Required triggers:
+
+- `package.json` version changes
+- root package entries in `package-lock.json` change because the package version changed
+- the user asks for PR, release, changelog, or handoff text
+- the working change alters published package behavior
+
+Optional trigger:
+
+- internal-only maintenance that would benefit from a reusable PR summary
+
+## Folder
+
+Write change notes under `changes/`.
+
+Use one file per cohesive working change:
+
+```text
+changes/YYYY-MM-DD-short-slug.md
+```
+
+Use dates from the current local session date. Keep slugs short, lowercase, and grep-friendly.
+
+## Required Shape
+
+Each change note must use this structure:
+
+```markdown
+# Short Change Title
+
+Version action: none|patch|minor|major
+
+## PR Summary
+
+- Concise maintainer-facing summary.
+
+## Release Note
+
+- User-facing release text, or `None; internal-only change.`
+
+## Verification
+
+- Command run, or skipped check with reason.
+```
+
+## Rules
+
+- `Version action` must match [versioning.md](versioning.md).
+- If `Version action` is `patch`, `minor`, or `major`, the package version must change in the same working change.
+- If the package version changes, a matching change note is required because Truthmark releases whenever the package version changes.
+- Internal-only repository standards may use `Version action: none`.
+- Release notes describe published package behavior, not private repo maintenance.
+- Keep notes compact; they are source material for PR and release descriptions, not canonical product truth.
+
+## Agent Output
+
+When reporting change-note work, state only:
+
+- change note path
+- version action
+- whether release text is present or intentionally `None`

docs/standards/pre-completion-checklist.md

@@ -5,6 +5,8 @@ last_reviewed: 2026-05-13
 source_of_truth:
   - testing-and-verification.md
   - documentation-governance.md
+  - versioning.md
+  - change-notes.md
 ---
 
 # Pre-Completion Checklist
@@ -20,6 +22,8 @@ Use this checklist before declaring Truthmark work complete.
 - If this was a major product, onboarding, install, command, positioning, or workflow change, did you review the root [README.md](../../README.md) and update stale user-facing claims, examples, or command sequences?
 - If the root README changed materially, did the localized README variants change in the same working change? If not, stop unless you have an explicit repo-authorized reason they intentionally remain different, and state that reason. A passing verification command does not waive this gate.
 - If canonical routing changed, did [docs/truthmark/areas.md](../truthmark/areas.md) change too?
+- If the change is PR-worthy, release-worthy, or changes the package version, did you add or update a `changes/` note using [docs/standards/change-notes.md](change-notes.md)?
+- If any package version or release/version policy changed, did you apply [docs/standards/versioning.md](versioning.md) before accepting the version?
 - If [AGENTS.md](../../AGENTS.md) changed, did manual edits stay outside the managed Truthmark block?
 - Did you run the narrowest meaningful verification command from [docs/standards/testing-and-verification.md](testing-and-verification.md)?
 - If a normally expected verification step was skipped, did you state the reason explicitly?

docs/standards/testing-and-verification.md

@@ -5,6 +5,7 @@ last_reviewed: 2026-05-13
 source_of_truth:
   - ../../package.json
   - ../truth/contracts.md
+  - versioning.md
 ---
 
 # Testing And Verification
@@ -44,6 +45,7 @@ If a linked `truthmark` binary points at this checkout's `dist/main.js`, `truthm
 - Run `npm run dev -- check` when canonical docs, authority order, or areas routing changes.
 - Run `npm run check` before closing out broader code changes unless a narrower command is the only relevant one.
 - Run `npm run release:check` before publishing or handing off release-sensitive packaging changes.
+- Run `npm run dev -- init --json`, inspect generated version-marker diffs, and then run `npm run dev -- check` when the package version changes.
 
 ## Documentation-Only Changes
 

docs/standards/versioning.md

@@ -0,0 +1,83 @@
+---
+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 version markers follow the package version only after `truthmark init` is rerun.
+
+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, and version 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
+
+When changing a version number:
+
+1. Decide the bump class before editing the version and state the rationale in the handoff, PR, or release note.
+2. Create or update the matching `changes/` note from [change-notes.md](change-notes.md).
+3. Update `package.json` and the root package entries in `package-lock.json` together.
+4. Rerun `truthmark init` only when the package version actually changes, then inspect generated version-marker diffs.
+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
+- files changed or intentionally left unchanged
+- matching change note path when a version changes
+- verification run or explicitly skipped