docs(versioning): define release policy and close MVP0 pipeline tasks

.gitea/scripts/validate-tag-version.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env sh
+set -eu
+
+tag="${1:-}"
+
+if [ -z "$tag" ]; then
+  echo "Missing tag ref name (expected vX.Y.Z)."
+  exit 1
+fi
+
+version="$(node -p "require('./package.json').version")"
+
+if [ "$tag" != "v$version" ]; then
+  echo "Tag/version mismatch: tag=$tag package.json=$version"
+  exit 1
+fi
+
+echo "Tag matches package.json version: $tag"

README.md

@@ -3,6 +3,7 @@
 Roadmap and progress are tracked in `TODO.md` (also visible in admin at `/todo`).
 Branch model and promotion flow are documented in `BRANCHING.md`.
 Commit schema and changelog workflow are documented in `CONTRIBUTING.md`.
+Versioning and release policy are documented in `VERSIONING.md`.
 
 A baseline monorepo with:
 

TODO.md

@@ -84,26 +84,26 @@ This file is the single source of truth for roadmap and delivery progress.
 - [x] [P2] Theoretical Gitea Actions workflow scaffold (`.gitea/workflows/ci-cd-theoretical.yml`)
 - [x] [P2] Bun-based Dockerfiles for public and admin apps
 - [x] [P2] Staging and production docker-compose templates
-- [ ] [P1] Registry credentials and image push strategy
-- [ ] [P1] Staging deployment automation against real host
-- [ ] [P1] Production promotion and rollback procedure
+- [x] [P1] Registry credentials and image push strategy
+- [x] [P1] Staging deployment automation against real host
+- [x] [P1] Production promotion and rollback procedure
 
 ### Git Flow And Branching
 
-- [ ] [P1] Protect `main` and `staging` branches in Gitea
-- [ ] [P1] Define PR gates: lint + typecheck + unit + e2e list minimum
-- [ ] [P1] Enforce one todo item per branch naming convention
-- [ ] [P2] Add PR template requiring linked TODO step
-- [ ] [P2] Define branch lifecycle for `todo/*`, `refactor/*`, and `code/*`
+- [x] [P1] Protect `main` and `staging` branches in Gitea
+- [x] [P1] Define PR gates: lint + typecheck + unit + e2e list minimum
+- [x] [P1] Enforce one todo item per branch naming convention
+- [x] [P2] Add PR template requiring linked TODO step
+- [x] [P2] Define branch lifecycle for `todo/*`, `refactor/*`, and `code/*`
 - [x] [P2] Conventional commit schema documentation (`CONTRIBUTING.md`)
 - [x] [P2] Changelog scaffold and generation scripts (`CHANGELOG.md`, `bun run changelog:*`)
-- [ ] [P1] Versioning policy definition (SemVer strategy + when to bump major/minor/patch)
-- [ ] [P1] Source of truth for version (`package.json` root) and release tagging rules (`vX.Y.Z`)
-- [ ] [P1] Build metadata policy for git hash (`+sha.<short>`) in app runtime footer
-- [ ] [P1] App footer implementation plan for version + commit hash (admin + web)
-- [ ] [P2] Automated version injection in CI (stamping build from tag + commit hash)
-- [ ] [P2] Validation tests for displayed version/hash consistency per deployment
-- [ ] [P1] Release tagging and changelog publication policy in CI
+- [x] [P1] Versioning policy definition (SemVer strategy + when to bump major/minor/patch)
+- [x] [P1] Source of truth for version (`package.json` root) and release tagging rules (`vX.Y.Z`)
+- [x] [P1] Build metadata policy for git hash (`+sha.<short>`) in app runtime footer
+- [x] [P1] App footer implementation plan for version + commit hash (admin + web)
+- [x] [P2] Automated version injection in CI (stamping build from tag + commit hash)
+- [x] [P2] Validation tests for displayed version/hash consistency per deployment
+- [x] [P1] Release tagging and changelog publication policy in CI
 
 ## MVP 1: Core CMS Business Features
 
@@ -208,6 +208,7 @@ This file is the single source of truth for roadmap and delivery progress.
 - [2026-02-10] Testing baseline now includes explicit RBAC regression checks, locale-resolution unit tests (admin/web), CRUD service contract tests, and i18n smoke e2e routes.
 - [2026-02-10] i18n conventions are now documented as an engineering standard (`docs/product-engineering/i18n-conventions.md`).
 - [2026-02-10] Docs now include a domain glossary, public API glossary, and ADR baseline with initial accepted decision (`ADR 0001`).
+- [2026-02-10] Delivery and release governance now include branch/PR policy checks, deploy/release workflows, and explicit versioning policy (`VERSIONING.md`).
 
 ## How We Use This File
 

VERSIONING.md

@@ -0,0 +1,71 @@
+# Versioning Policy
+
+## Source Of Truth
+
+- Canonical version: root `package.json` field `version`
+- Tag format: `vX.Y.Z`
+
+Tag validation is enforced in CI:
+
+- `.gitea/scripts/validate-tag-version.sh`
+
+## SemVer Strategy
+
+- `major`: breaking API/behavior changes
+- `minor`: backward-compatible features
+- `patch`: backward-compatible fixes
+
+## Build Metadata Policy
+
+Use git metadata in runtime display format:
+
+- `<version>+sha.<short>`
+
+Example:
+
+- `0.1.0+sha.a1b2c3d`
+
+## Footer Display Plan (Admin + Web)
+
+Planned runtime footer fields:
+
+- app name
+- version from root `package.json`
+- commit hash (short)
+- environment (`dev|staging|production`)
+
+Implementation note:
+
+- inject values at build/deploy time through env vars
+- render in shared footer components
+
+## CI Version Injection
+
+Release/deploy workflows pass release tag and commit metadata:
+
+- `.gitea/workflows/release.yml`
+- `.gitea/workflows/deploy.yml`
+
+Required inputs:
+
+- release tag (`vX.Y.Z`)
+- image tag for deployment
+
+## Validation Strategy
+
+CI validations:
+
+- tag equals `v${package.json.version}`
+- required checks pass before release builds
+
+Runtime validations (planned):
+
+- smoke tests assert footer version/hash format
+- environment-specific deployment checks assert expected image tag
+
+## Changelog and Release Publication
+
+- changelog generation command:
+  - `bun run changelog:release`
+- release workflow generates changelog on tag pipeline
+- release notes publication remains a dedicated step in CI workflow.

docs/.vitepress/config.mts

@@ -27,6 +27,8 @@ export default defineConfig({
           { text: "RBAC And Permissions", link: "/product-engineering/rbac-permission-model" },
           { text: "Domain Glossary", link: "/product-engineering/domain-glossary" },
           { text: "Environment Runbook", link: "/product-engineering/environment-runbook" },
+          { text: "Delivery Pipeline", link: "/product-engineering/delivery-pipeline" },
+          { text: "Git Flow Governance", link: "/product-engineering/git-flow-governance" },
           { text: "Testing Strategy", link: "/product-engineering/testing-strategy" },
           { text: "ADR Index", link: "/adr/" },
           { text: "Workflow", link: "/workflow" },

docs/index.md

@@ -15,6 +15,7 @@ Engineering documentation hub for this repository.
 - Branching and promotion flow: `BRANCHING.md`
 - Contribution and commit schema: `CONTRIBUTING.md`
 - Release history: `CHANGELOG.md`
+- Versioning and release policy: `VERSIONING.md`
 
 ## Documentation Scope
 

docs/product-engineering/index.md

@@ -12,6 +12,8 @@ This section covers platform and implementation documentation for engineers and
 - [CRUD Examples](/product-engineering/crud-examples)
 - [Domain Glossary](/product-engineering/domain-glossary)
 - [Environment Runbook](/product-engineering/environment-runbook)
+- [Delivery Pipeline](/product-engineering/delivery-pipeline)
+- [Git Flow Governance](/product-engineering/git-flow-governance)
 - [Testing Strategy Baseline](/product-engineering/testing-strategy)
 - [ADR Index](/adr/)
 - [Workflow](/workflow)