Product Version: One Fact, One Editor

"A repo has a dozen version numbers. Exactly one of them is the product, and exactly one thing may change it."

Which Version, Exactly?

Say a repo is 'version 1.2.0.' Which one? The npm package version? The native bundle build number? The database schema version? The API/protocol version? The model version? The deployment number? The Git tag? A mature project has many of these, and they legitimately move independently. Firelink names one of them the product version — the human-facing release — and gives it a single home: a small file, cwk-product.json, holding a product id and a normalized SemVer string (no leading v; prerelease and build parts allowed when they carry real meaning).

The values are meaningful by convention: 0.0.0 is a scaffold shell, 0.y.z is an unstable product contract, and 1.0.0 declares the first stable production contract. Display surfaces add the v back for readers; the stored value stays clean.

One Owner, One Editor, One Field

This is one-owner-per-fact made concrete, and it goes one step further: not just one owner, but one editor. Firelink reads the manifest before any legacy heuristic source, and heuristics remain read-only fallbacks for members without a valid manifest. The Web repository card is the only thing that may write it, and it may change only the version field — through a previewed, audited flow that requires a clean worktree, records coop history before the commit, preserves every other byte in the file, and rejects a lower SemVer precedence unless a downgrade override is explicitly enabled. The Native Launcher is entirely read-only here.

Why the Ceremony Is the Point

A version bump looks trivial, which is exactly why it's dangerous to leave unguarded. Bumping a product version is a claim — 'this is now 1.0.0, a stable contract.' If any surface could scribble that number, the claim would mean nothing. By making the bump a single-field, previewed, history-recorded, non-force-pushed operation from one editor, Firelink keeps the version honest: it changed on purpose, someone can see exactly what changed, and the change is a real commit with a real trail.

For a fact that carries a claim, name not just one owner but one editor, and make the edit a previewed, audited, minimal-diff operation. 'Only this surface, only this field, only through this reviewed flow' turns a number anyone could fake into a statement you can trust.

Code

cwk-product.json — one fact with one home·json

{
  "schema_version": 1,
  "product_id": "cwkFirelink",
  "version": "1.0.0"
}

// This 'version' is ONLY the human-facing product release. It is NOT:
//   - the npm/package version        - the API / protocol version
//   - the native bundle build number  - the model version
//   - the database schema version     - the git tag / commit
// 0.0.0 = scaffold, 0.y.z = unstable, 1.0.0 = first stable contract.
//
// Editable by exactly one thing (the Web repo card), one field ('version'),
// through: clean worktree -> preview diff -> record coop history -> commit
// -> non-force push. Lower precedence is rejected without an explicit override.

Exercise

List every 'version number' in a project you know — package, build, schema, API, git tag, and the human-facing release. For each, name who or what is allowed to change it and through what process. Find the one that is the 'product release' to a user, and ask: could any surface change it by accident right now? If yes, design the one-editor-one-field-one-flow guard that would make that bump a deliberate, auditable claim.

Hint

Most projects have no single 'product version' at all — they let the git tag or the package version stand in, and then those drift apart from what users actually see. Naming the product version explicitly, with one editor, is half the fix.

Product Version: One Fact, One Editor

Which Version, Exactly?

One Owner, One Editor, One Field

Why the Ceremony Is the Point

Code

External links

Exercise

Progress

Comments 0