@keelcore/standards 0.9.7 → 0.10.0

package/governance/platform.md

@@ -1,156 +1,150 @@
 # Platform Architecture Standards
 
-These rules govern platform-level decisions across networking, DNS, TLS, WAF, and traffic management.
-They are non-negotiable unless explicitly superseded by a signed ADR.
+These rules govern platform-level decisions across networking, DNS, TLS, WAF, and traffic management. They are
+non-negotiable unless explicitly superseded by a signed ADR.
 
-**Maturity:** Required
-**Version:** 1.0.0
-**Last Reviewed:** 2026-03-09
+**Maturity:** Required **Version:** 1.0.0 **Last Reviewed:** 2026-03-09
 
 ## Governance Process
 
 ### Decision-Making (DACI)
 
-1. All platform architecture decisions use DACI: one Driver, one Approver (Architecture Review Board
-   chair or delegate), Consulted stakeholders, and Informed parties.
+1. All platform architecture decisions use DACI: one Driver, one Approver (Architecture Review Board chair or delegate),
+   Consulted stakeholders, and Informed parties.
 2. The Driver authors the RFC and owns shepherding it through review.
 3. The Approver has final authority; no decision is binding without Approver sign-off.
 4. Decisions that affect more than one service domain require ARB review before implementation.
 
 ### RFC Process
 
-5. Any change to platform standards, vendor selection, or network topology requires an RFC.
-6. RFC template: problem statement, proposed solution, alternatives considered, rollout plan, rollback plan.
-7. RFC comment period is a minimum of five business days for standard changes; urgent security patches
-   may compress to 24 hours with ARB chair notification.
-8. Accepted RFCs are archived in `docs/rfc/` with status and the date of acceptance.
+1. Any change to platform standards, vendor selection, or network topology requires an RFC.
+2. RFC template: problem statement, proposed solution, alternatives considered, rollout plan, rollback plan.
+3. RFC comment period is a minimum of five business days for standard changes; urgent security patches may compress to
+   24 hours with ARB chair notification.
+4. Accepted RFCs are archived in `docs/rfc/` with status and the date of acceptance.
 
 ### Architecture Review Board (ARB)
 
-9. ARB meets on a defined cadence (minimum monthly); decisions and attendance are published to the
-   engineering wiki within five business days of each meeting.
-10. ARB publishes a versioned Architecture Standards document at least once per quarter.
-11. Previous versions of Architecture Standards are archived and permanently accessible.
+1. ARB meets on a defined cadence (minimum monthly); decisions and attendance are published to the engineering wiki
+   within five business days of each meeting.
+2. ARB publishes a versioned Architecture Standards document at least once per quarter.
+3. Previous versions of Architecture Standards are archived and permanently accessible.
 
 ## Domain and IP
 
 ### Domain Registrar
 
-12. All domains are registered through the approved corporate registrar (documented in the internal
-    vendor registry). Personal or team-owned registrar accounts are prohibited for production domains.
-13. Domain transfers require ARB approval and a change record.
-14. WHOIS privacy protection is enabled on all externally registered domains.
+1. All domains are registered through the approved corporate registrar (documented in the internal vendor registry).
+   Personal or team-owned registrar accounts are prohibited for production domains.
+2. Domain transfers require ARB approval and a change record.
+3. WHOIS privacy protection is enabled on all externally registered domains.
 
 ### IP Address Management
 
-15. IP allocations are managed through the approved IPAM vendor (documented in the internal vendor registry).
-16. All IP blocks are tagged with owner, environment, and region.
-17. IPv4 and IPv6 are both required for all new public-facing services. Dual-stack is the baseline; IPv4-only
-    services are not accepted for new deployments.
-18. Private RFC 1918 ranges are used for internal pod and node networks. Overlap with VPN or on-premises
-    ranges must be approved through the IPAM change process.
+1. IP allocations are managed through the approved IPAM vendor (documented in the internal vendor registry).
+2. All IP blocks are tagged with owner, environment, and region.
+3. IPv4 and IPv6 are both required for all new public-facing services. Dual-stack is the baseline; IPv4-only services
+   are not accepted for new deployments.
+4. Private RFC 1918 ranges are used for internal pod and node networks. Overlap with VPN or on-premises ranges must be
+   approved through the IPAM change process.
 
 ## DNS
 
 ### Zone Management
 
-19. DNS zones are managed through the approved DNS vendor (documented in the internal vendor registry).
-    Manual zone edits via vendor UI are prohibited except in a documented break-glass scenario.
-20. All zone changes are driven from infrastructure-as-code (Terraform, Pulumi, or equivalent) in a
-    version-controlled repository. Zone state is reconciled on every deployment.
-21. Internal and external zones are segregated. Internal zone resolvers are not exposed to the public internet.
+1. DNS zones are managed through the approved DNS vendor (documented in the internal vendor registry). Manual zone edits
+   via vendor UI are prohibited except in a documented break-glass scenario.
+2. All zone changes are driven from infrastructure-as-code (Terraform, Pulumi, or equivalent) in a version-controlled
+   repository. Zone state is reconciled on every deployment.
+3. Internal and external zones are segregated. Internal zone resolvers are not exposed to the public internet.
 
 ### Required Record Types
 
-22. Public services must expose: A, AAAA, and the appropriate CNAME or alias records.
-23. Email domains must have SPF, DKIM, and DMARC records. DMARC policy must be `p=quarantine` or stricter
-    in production.
-24. Wildcard DNS records (`*.example.com`) are permitted only for edge/ingress controllers that validate
-    per-host routing internally. Wildcard records must not resolve to application pods directly.
-25. Internal service discovery uses a dedicated internal TLD (e.g., `.internal` or cluster DNS suffix).
-    Internal records are never propagated to public resolvers.
+1. Public services must expose: A, AAAA, and the appropriate CNAME or alias records.
+2. Email domains must have SPF, DKIM, and DMARC records. DMARC policy must be `p=quarantine` or stricter in production.
+3. Wildcard DNS records (`*.example.com`) are permitted only for edge/ingress controllers that validate per-host routing
+   internally. Wildcard records must not resolve to application pods directly.
+4. Internal service discovery uses a dedicated internal TLD (e.g., `.internal` or cluster DNS suffix). Internal records
+   are never propagated to public resolvers.
 
 ## TLS and Certificate Management
 
 ### Certificate Issuance
 
-26. TLS certificates for public endpoints are issued from an approved CA vendor (documented in the internal
-    vendor registry). Self-signed certificates are prohibited on any public-facing endpoint.
-27. Certificate issuance and renewal must use the ACME protocol. Manual certificate downloads and uploads
-    are prohibited except in a documented break-glass scenario.
-28. Certificates are provisioned and renewed automatically. Expiry-based alerts fire at 30 days and again
-    at 7 days before expiration.
+1. TLS certificates for public endpoints are issued from an approved CA vendor (documented in the internal vendor
+   registry). Self-signed certificates are prohibited on any public-facing endpoint.
+2. Certificate issuance and renewal must use the ACME protocol. Manual certificate downloads and uploads are prohibited
+   except in a documented break-glass scenario.
+3. Certificates are provisioned and renewed automatically. Expiry-based alerts fire at 30 days and again at 7 days
+   before expiration.
 
 ### Mutual TLS (mTLS)
 
-29. East-west traffic between services must use mTLS. Plaintext service-to-service communication is
-    prohibited in staging and production.
-30. mTLS certificates are issued by the internal PKI (SPIFFE/SPIRE or equivalent). Leaf certificates
-    rotate on a maximum 24-hour lifetime. Rotation is automatic and zero-downtime.
-31. mTLS policy is enforced at the service mesh layer, not individually per application.
+1. East-west traffic between services must use mTLS. Plaintext service-to-service communication is prohibited in staging
+   and production.
+2. mTLS certificates are issued by the internal PKI (SPIFFE/SPIRE or equivalent). Leaf certificates rotate on a maximum
+   24-hour lifetime. Rotation is automatic and zero-downtime.
+3. mTLS policy is enforced at the service mesh layer, not individually per application.
 
 ### Supported Protocols and Cipher Suites
 
-32. Minimum TLS version: TLS 1.2. TLS 1.3 is required for all new integrations.
-33. TLS 1.0 and TLS 1.1 are prohibited on all endpoints.
-34. Cipher suites: prefer ECDHE key exchange with AES-GCM or ChaCha20-Poly1305. RC4, DES, 3DES,
-    and export-grade ciphers are prohibited. DHE suites below 2048-bit DH parameters are prohibited.
-35. HSTS is required on all HTTPS endpoints with `max-age` of at least one year.
+1. Minimum TLS version: TLS 1.2. TLS 1.3 is required for all new integrations.
+2. TLS 1.0 and TLS 1.1 are prohibited on all endpoints.
+3. Cipher suites: prefer ECDHE key exchange with AES-GCM or ChaCha20-Poly1305. RC4, DES, 3DES, and export-grade ciphers
+   are prohibited. DHE suites below 2048-bit DH parameters are prohibited.
+4. HSTS is required on all HTTPS endpoints with `max-age` of at least one year.
 
 ## Web Application Firewall (WAF) and DDoS
 
 ### WAF
 
-36. All public HTTP/HTTPS ingress passes through the WAF layer before reaching application pods.
-37. The OWASP Core Rule Set (CRS) is enforced in blocking mode. Detection-only mode is not
-    acceptable for production. Tuning exceptions require a documented rule with justification.
-38. WAF rules are version-controlled. Rule changes follow the RFC process.
-39. WAF logs are ingested into the central log aggregation platform with a minimum 90-day retention.
+1. All public HTTP/HTTPS ingress passes through the WAF layer before reaching application pods.
+2. The OWASP Core Rule Set (CRS) is enforced in blocking mode. Detection-only mode is not acceptable for production.
+   Tuning exceptions require a documented rule with justification.
+3. WAF rules are version-controlled. Rule changes follow the RFC process.
+4. WAF logs are ingested into the central log aggregation platform with a minimum 90-day retention.
 
 ### DDoS Protection
 
-40. All public endpoints are protected by volumetric DDoS mitigation at the network edge.
-41. L7 DDoS (HTTP flood) mitigation is enforced by the WAF layer with rate limiting rules.
-42. Incident response runbooks for DDoS events are maintained and reviewed quarterly.
+1. All public endpoints are protected by volumetric DDoS mitigation at the network edge.
+2. L7 DDoS (HTTP flood) mitigation is enforced by the WAF layer with rate limiting rules.
+3. Incident response runbooks for DDoS events are maintained and reviewed quarterly.
 
 ## Security Headers
 
-43. All HTTP responses from public endpoints must include:
-    - `Strict-Transport-Security: max-age=31536000; includeSubDomains; preload`
-    - `X-Content-Type-Options: nosniff`
-    - `X-Frame-Options: DENY`
-    - `Content-Security-Policy` (service-specific, reviewed by security team)
-    - `Referrer-Policy: strict-origin-when-cross-origin`
-    - `Permissions-Policy` (restrictive default; expand per-service with justification)
-44. `Server` and `X-Powered-By` response headers must be suppressed or overridden to not reveal
-    implementation details.
+1. All HTTP responses from public endpoints must include:
+   - `Strict-Transport-Security: max-age=31536000; includeSubDomains; preload`
+   - `X-Content-Type-Options: nosniff`
+   - `X-Frame-Options: DENY`
+   - `Content-Security-Policy` (service-specific, reviewed by security team)
+   - `Referrer-Policy: strict-origin-when-cross-origin`
+   - `Permissions-Policy` (restrictive default; expand per-service with justification)
+2. `Server` and `X-Powered-By` response headers must be suppressed or overridden to not reveal implementation details.
 
 ## Traffic Management
 
 ### Payload Limits
 
-45. Default maximum upload size: 10 MB. Services requiring larger uploads must document and configure
-    an explicit limit; unbounded uploads are prohibited.
-46. Maximum request body size: 1 MB by default for API endpoints. Streaming endpoints must implement
-    backpressure.
-47. Maximum response size is bounded by the service contract. Unbounded response streaming must
-    implement flow control.
+1. Default maximum upload size: 10 MB. Services requiring larger uploads must document and configure an explicit limit;
+   unbounded uploads are prohibited.
+2. Maximum request body size: 1 MB by default for API endpoints. Streaming endpoints must implement backpressure.
+3. Maximum response size is bounded by the service contract. Unbounded response streaming must implement flow control.
 
 ### Rate Limiting
 
-48. Global rate limiting is enforced at the edge/ingress layer.
-49. Per-service rate limits are configured and documented in each service's runbook.
-50. Rate limit responses use HTTP 429 with a `Retry-After` header.
-51. Rate limit state is shared across edge replicas (e.g., Redis-backed or edge-native distributed
-    counters). Per-replica rate limiting that allows bypass via replica selection is prohibited.
+1. Global rate limiting is enforced at the edge/ingress layer.
+2. Per-service rate limits are configured and documented in each service's runbook.
+3. Rate limit responses use HTTP 429 with a `Retry-After` header.
+4. Rate limit state is shared across edge replicas (e.g., Redis-backed or edge-native distributed counters). Per-replica
+   rate limiting that allows bypass via replica selection is prohibited.
 
 ### Session Management
 
-52. Session tokens are cryptographically random with a minimum of 128 bits of entropy.
-53. Session lifetime: configurable per service, with a maximum idle timeout of 15 minutes and a
-    maximum absolute session lifetime of 8 hours for human-facing sessions.
-54. Sessions are invalidated server-side on logout. Client-side deletion alone is insufficient.
-55. Session refresh tokens must be rotated on every use.
+1. Session tokens are cryptographically random with a minimum of 128 bits of entropy.
+2. Session lifetime: configurable per service, with a maximum idle timeout of 15 minutes and a maximum absolute session
+   lifetime of 8 hours for human-facing sessions.
+3. Sessions are invalidated server-side on logout. Client-side deletion alone is insufficient.
+4. Session refresh tokens must be rotated on every use.
 
 ## Do Not
 

package/governance/release-policy.md

@@ -1,76 +1,131 @@
 # Release Policy
 
-**Maturity:** Required
-**Version:** 1.0.0
-**Last Reviewed:** 2026-03-11
+**Maturity:** Required **Version:** 1.1.0 **Last Reviewed:** 2026-10-30
 
-This document covers how Keel versions are tagged and released. The authoritative
-policy lives in the [keelcore/standards `ci.md`](ci.md)
-under **Release Tagging**. This document is the developer-facing how-to that
-complements that policy.
+This document covers how a project that follows the keelcore standards tags and releases a version. The authoritative
+policy lives in [`ci.md`](ci.md) under **Release Tagging**. This document is the developer-facing how-to that
+complements that policy. It applies to every project as written; what a project may change, and where, is set out in
+[Project Customization](#project-customization) below.
 
 ---
 
 ## Versioning Specification
 
-Keel follows **Semantic Versioning 2.0.0** — [https://semver.org](https://semver.org).
-That document is the canonical reference; the rules below are derived from it and
-must not contradict it.
+Projects follow **Semantic Versioning 2.0.0** — [https://semver.org](https://semver.org). That document is the
+canonical reference; the rules below are derived from it and must not contradict it.
 
 Key semver.org rules in force here:
 
-- Version numbers take the form `MAJOR.MINOR.PATCH` where each component is a
-  non-negative integer with no leading zeroes.
+- Version numbers take the form `MAJOR.MINOR.PATCH` where each component is a non-negative integer with no leading
+  zeroes.
 - MAJOR is incremented for incompatible API changes; MINOR and PATCH reset to 0.
 - MINOR is incremented for new backward-compatible functionality; PATCH resets to 0.
 - PATCH is incremented for backward-compatible bug fixes only.
-- Major version zero (`0.y.z`) is for initial development. The public API is not
-  yet stable and anything may change at any time.
+- Major version zero (`0.y.z`) is for initial development. The public API is not yet stable and anything may change at
+  any time.
 - `1.0.0` defines the first stable public API.
-- Pre-release identifiers (`-alpha.1`, `-rc.2`, etc.) and build metadata (`+sha`)
-  are valid semver extensions but are **not supported by `create-release.sh`** at
-  this time. `--force` only accepts bare `MAJOR.MINOR.PATCH` versions.
+- Pre-release identifiers (`-alpha.1`, `-rc.2`, etc.) and build metadata (`+sha`) are valid semver extensions but are
+  **not supported by `create-release.sh`** at this time. `--force` only accepts bare `MAJOR.MINOR.PATCH` versions.
 
-**Scope of automated detection:** The script detects breaking changes by diffing
-the config YAML field surface (`pkg/config/schema.yaml`). Other API-breaking
-changes — Go type signatures, HTTP API shape, security policy, behavior semantics
-— are not automatically detected. Use `--force` with the appropriate bump level
-for those cases.
+Git tags are the only source of truth for versions. Projects keep no version file and make no version-bump commit.
+
+**Scope of automated detection:** each project's hook detects only the surface it is written to diff. Breaking changes
+it cannot see — Go type signatures, HTTP API shape, security policy, behavior semantics — are the developer's call: use
+`--force` with the appropriate bump level.
 
 ---
 
 ## Core Rule: Tags Are Developer-Created, Never CI-Created
 
-CI reacts to pushed tags to run the release pipeline. CI never creates tags.
-A version tag is a human commitment about what a commit represents — that
-decision requires review and cannot be automated.
+CI reacts to pushed tags to run the release pipeline. CI never creates tags. A version tag is a human commitment about
+what a commit represents — that decision requires review and cannot be automated.
 
 ---
 
 ## Tooling
 
-| Script | Purpose |
-| --- | --- |
-| `scripts/release/create-release.sh` | Compute, approve, tag, and push a release |
-| `scripts/release/gen-schema.sh` | Regenerate `pkg/config/schema.yaml` after config changes |
-| `cmd/config-schema/main.go` | Go tool: reflection-walk of `config.Config` → dotted YAML paths |
-| `make gen-schema` | Alias for `gen-schema.sh` |
-| `make create-release` | Alias for `create-release.sh` (auto mode) |
-| `make create-release FORCE=v1.0.0` | Alias for `create-release.sh --force v1.0.0` |
+| Script or target                            | Purpose                                                               |
+| ------------------------------------------- | --------------------------------------------------------------------- |
+| `scripts/release/create-release.sh`         | Canonical (from `keelcore/standards`): compute, approve, tag and push |
+| `scripts/release/create-release.local.sh`   | The project's own bump hook; never canonical, never synced            |
+| `make create-release`                       | Alias for `create-release.sh` (auto mode)                             |
+| `make create-release FORCE=v1.0.0`          | Alias for `create-release.sh --force v1.0.0`                          |
+| `make create-release DRY_RUN=1`             | Alias for `create-release.sh --dry-run`: no prompt, no tag, no push   |
+| `make create-release-local PREV_TAG=vX.Y.Z` | Run the hook alone against a previous tag                             |
 
 ---
 
 ## How Version Bumps Are Computed
 
-The script diffs `pkg/config/schema.yaml` at the previous tag against the file
-at `HEAD`. The schema lists every fully-flattened dotted YAML field path in
-`config.Config` (e.g. `sidecar.circuit_breaker.reset_timeout`).
+`create-release.sh` gets the bump level from the hook at `scripts/release/create-release.local.sh` in the git toplevel
+of the repo being released — inside a consumer, the consumer's hook, never the copy in `.standards`. The driver calls it
+as `create-release.local.sh <previous-tag>`, and the hook prints two lines to stdout:
+
+1. the bump level: `major`, `minor` or `patch`;
+2. a one-line tag subject (empty means `release vX.Y.Z`).
+
+Anything the hook writes to stderr is shown to the developer and recorded in the tag body. A non-zero exit aborts the
+release. With no hook, every release is a `patch`.
+
+| Hook reports | Meaning                               | semver.org rationale                                                       |
+| ------------ | ------------------------------------- | -------------------------------------------------------------------------- |
+| `major`      | Breaking change to the public surface | Incompatible API change ([item 4](https://semver.org/#spec-item-4))        |
+| `minor`      | New backward-compatible functionality | Backward-compatible addition ([item 5](https://semver.org/#spec-item-5))   |
+| `patch`      | No public surface change              | Bug fixes and internal changes ([item 6](https://semver.org/#spec-item-6)) |
 
-| Schema change | Bump level | semver.org rationale |
-| --- | --- | --- |
-| One or more fields **removed** | **major** — breaking change | Removing a field is an incompatible API change ([item 4](https://semver.org/#spec-item-4)) |
-| One or more fields **added**, none removed | **minor** — new feature | New fields are backward-compatible additions ([item 5](https://semver.org/#spec-item-5)) |
-| No field surface changes | **patch** — internal improvements | No public API surface change ([item 6](https://semver.org/#spec-item-6)) |
+While the major version is 0 ([item 9](https://semver.org/#spec-item-9)), `create-release.sh` demotes the bump one step
+(major → minor, minor → patch) and adds `(pre-1.0 demotion)` to the tag subject. A patch stays a patch when there are
+commits since the previous tag; with none, there is nothing to release.
+
+---
+
+## Project Customization
+
+A project customizes releases in three places, all owned by the project. Everything else in this policy applies
+unchanged.
+
+| What                 | Where                                                  | Purpose                                          |
+| -------------------- | ------------------------------------------------------ | ------------------------------------------------ |
+| Bump policy          | `scripts/release/create-release.local.sh`              | Decide the bump level from the project's surface |
+| Hook target          | `create-release-local` in the project's `Makefile`     | Run the hook alone; satisfies `make audit`       |
+| Release how-to       | The project's `docs/release-policy.md`                 | Document the project's customization             |
+
+### The bump hook
+
+- It defines the project's public surface for versioning: a config schema, an API spec, exported symbols, a changelog —
+  whatever a consumer of the project depends on.
+- It follows the contract in [How Version Bumps Are Computed](#how-version-bumps-are-computed): called with the previous
+  tag, two lines on stdout, findings on stderr, non-zero exit to abort.
+- It reports the raw change. It does not apply pre-1.0 demotion or add the demotion note; the driver does both.
+- It is read-only and deterministic: it runs from the git toplevel against the clean `HEAD`, and never tags, commits,
+  pushes or writes outside temporary files.
+- It is never canonical. `verify-canonical` and `governance-refresh` skip `*.local.sh`, so `keelcore/standards`' own
+  hook is never copied into a project and a project's hook is never overwritten.
+
+### The project's release-policy document
+
+- It incorporates this policy by reference: it links to `.standards/governance/release-policy.md` and states that the
+  standards policy applies in full.
+- It does not restate or contradict this policy. It contains only the project's customization:
+  - what the hook diffs, and why that is the project's public surface;
+  - the breaking changes the hook cannot see, which call for `--force`;
+  - how the hook's input is kept current (e.g. a generated schema and the check that keeps it fresh);
+  - project-specific tooling and anything the hook adds to the tag message.
+
+### Not customizable
+
+- Tags are created only by a developer running `make create-release`; never by CI.
+- `scripts/release/create-release.sh` is canonical and byte-identical in every project. Changes go to
+  `keelcore/standards` first.
+- The preconditions, pre-1.0 demotion, `--force` rules and the signed annotated tag.
+- Tags are the only version source; no version file, no version-bump commit.
+
+### Examples
+
+- **keel** — the hook diffs the config field set of `pkg/config/schema.yaml` at the previous tag against `HEAD`:
+  removed fields → major; added fields → minor; no change → patch. See keel's `docs/release-policy.md`.
+- **keelcore/standards** — the hook reads `CHANGELOG.md` `## [Unreleased]`: any `### Removed` entry → major; else any
+  `### Added` or `### Changed` entry → minor; else patch. An empty `[Unreleased]` fails.
 
 ---
 
@@ -79,93 +134,68 @@ at `HEAD`. The schema lists every fully-flattened dotted YAML field path in
 ```bash
 git checkout main && git pull --ff-only
 # ... merge your work ...
-./scripts/release/create-release.sh
+make create-release DRY_RUN=1   # optional preview
+make create-release
 ```
 
 The script will:
 
 1. Verify you are on `main`, your branch's configured upstream is in sync, and the working tree is clean.
-2. Compute the field diff and determine the bump level.
-3. Print the summary (fields added/removed, bump level, proposed tag message).
+2. Run the project's hook and compute the next version.
+3. Print the summary (the hook's findings, bump level, proposed tag subject).
 4. Prompt for `y/N` approval.
-5. On approval: create a signed annotated tag and push it to the upstream remote.
+5. On approval: create a signed annotated tag and push that one tag to the upstream remote.
 
-CI picks up the pushed tag and runs the release pipeline (build, sign, SBOM,
-publish).
+A dry run prints the version and the full tag message without prompting, tagging or pushing, and reports failed
+preconditions as warnings. CI picks up the pushed tag and runs the release pipeline (build, sign, SBOM, publish).
 
 ---
 
 ## Forcing a Specific Version
 
-Use `--force vX.Y.Z` to override the computed version. Only bare `MAJOR.MINOR.PATCH`
-versions are accepted — pre-release extensions (`-alpha.1`) and build metadata
-(`+sha`) are not supported.
-
-```bash
-./scripts/release/create-release.sh --force v1.0.0
-```
+Use `--force vX.Y.Z` (`make create-release FORCE=vX.Y.Z`) to override the computed version. Only bare
+`MAJOR.MINOR.PATCH` versions are accepted — pre-release extensions (`-alpha.1`) and build metadata (`+sha`) are not
+supported.
 
 ### Pre-1.0 rules (current major = 0)
 
-Per [semver.org item 9](https://semver.org/#spec-item-9), `0.y.z` is for initial
-development where the API is not yet stable. Only the following targets are accepted:
+Per [semver.org item 9](https://semver.org/#spec-item-9), `0.y.z` is for initial development where the API is not yet
+stable. Only the following targets are accepted:
 
 - Any `0.x.y` where `0.x.y > current` — normal initial-development progression.
-- Exactly `v1.0.0` — the stable API promotion per [semver.org item 10](https://semver.org/#spec-item-10),
-  regardless of detected bump level.
+- Exactly `v1.0.0` — the stable API promotion per [semver.org item 10](https://semver.org/#spec-item-10), regardless of
+  the hook's bump level.
 
 Forcing `v1.1.0`, `v2.0.0`, or any other version outside this range is rejected.
 
 ### Post-1.0 rules (current major ≥ 1)
 
-Once `1.0.0` is released the public API is stable. `--force` is restricted to
-exact single-step increments per semver.org's ordering rules:
-
-| `--force` target | Condition | Result |
-| --- | --- | --- |
-| `cur_maj.cur_min.(cur_pat+1)` | any | **Allowed** — single patch step |
-| `cur_maj.(cur_min+1).0` | any | **Allowed** — single minor step (e.g. internal improvements not reflected in schema diff) |
-| `(cur_maj+1).0.0` | breaking changes detected AND matches computed version | **Allowed** |
-| `(cur_maj+1).0.0` | no breaking changes, or doesn't match computed | **Rejected** — major bump requires a detected breaking change |
-| anything else | — | **Rejected** — must be a single-step increment |
-
----
-
-## Keeping schema.yaml Fresh
-
-`pkg/config/schema.yaml` is a committed artifact generated from `config.Config`
-by reflection. The pre-commit hook regenerates and stages it automatically
-whenever any `pkg/config/*.go` file is part of a commit — no manual step required.
-
-To regenerate it outside of a commit (e.g. to inspect the current output):
-
-```bash
-./scripts/release/gen-schema.sh
-# or
-make gen-schema
-```
+Once `1.0.0` is released the public API is stable. `--force` is restricted to exact single-step increments per
+semver.org's ordering rules:
 
-The consistency test suite enforces that `schema.yaml` is never stale — a
-mismatch between the committed file and the reflection output fails CI.
+| `--force` target              | Condition                                         | Result                                                                    |
+| ----------------------------- | ------------------------------------------------- | ------------------------------------------------------------------------- |
+| `cur_maj.cur_min.(cur_pat+1)` | any                                               | **Allowed** — single patch step                                           |
+| `cur_maj.(cur_min+1).0`       | any                                               | **Allowed** — single minor step (e.g. changes the hook cannot see)        |
+| `(cur_maj+1).0.0`             | hook reports `major` AND matches computed version | **Allowed**                                                               |
+| `(cur_maj+1).0.0`             | hook does not report `major`, or no match         | **Rejected** — a major bump requires the hook to report a breaking change |
+| anything else                 | —                                                 | **Rejected** — must be a single-step increment                            |
 
 ---
 
 ## What Goes in the Tag Message
 
-The script auto-generates a signed annotated tag with a structured message:
+The script generates a signed annotated tag with a structured message:
 
-- **Subject line:** `{bump}: {short summary}` (e.g. `minor: added 2 config field(s)`)
-- **Body:** full field list, bump level, previous/new version, commit SHA, and
-  provenance trailers (`Generated-by:`, `Schema:`)
+- **Subject line:** `{bump}: {hook subject}` (e.g. `minor: added 2 config field(s)`)
+- **Body:** bump level, previous/new version, commit SHA, the hook's findings, and the `Generated-by:` trailer
 
-The GitHub Release body is populated directly from the tag message via
-`gh release create --notes-from-tag`.
+The GitHub Release body can be populated directly from the tag message via `gh release create --notes-from-tag`.
 
 ---
 
 ## Emergency / Break-Glass
 
-If a critical patch must ship and the normal flow is blocked, follow the
-break-glass procedure in `docs/break-glass.md`. The bypass still requires two
-senior engineers and an incident record — it does not bypass the tag-creation
-requirement, only the precondition checks.
+If a critical patch must ship and the normal flow is blocked, follow the break-glass procedure in
+[`docs/break-glass.md`](../docs/break-glass.md). The bypass still requires two senior engineers and an incident record
+— it does not bypass the tag-creation requirement, only the precondition checks.