@oddessentials/repo-standards 3.0.0 → 3.1.0

package/README.md

@@ -68,7 +68,7 @@ The master spec includes a `meta` block that defines system-wide expectations:
 
 ## Structure of `config/standards.json`
 
-- `version` — schema version (currently `2`)
+- `version` — schema version (currently `3`)
 - `meta` — global rules and migration policy
 - `ciSystems` — supported CI platforms
   _(currently `github-actions`, `azure-devops`)_
@@ -102,6 +102,7 @@ The `version` field indicates schema compatibility:
 
 - `1` — Original schema
 - `2` — Adds `bazelHints`, `meta.executorHints.bazel` for Bazel support, `anyOfFiles`, `pinningNotes`, enforcement/severity levels, ratio-based coverage thresholds, Rust/Go stacks. Enforces strict validation with `additionalProperties: false`.
+- `3` — Expands release, build determinism, and provenance/CI automation requirements; adds unified release workflow and template automation guidance.
 
 Consumers should ignore unknown fields for forward compatibility.
 

package/dist/config/standards.csharp-dotnet.azure-devops.json

@@ -121,7 +121,7 @@
             "stage": "release"
           }
         },
-        "description": "Use MAJOR.MINOR.PATCH versioning with clear rules and automated changelog generation based on commit history.",
+        "description": "Use MAJOR.MINOR.PATCH versioning with clear rules and automated changelog generation based on commit history. Maintain a single canonical version source (for example, package.json or VERSION) that all release artifacts use.",
         "id": "semantic-versioning",
         "label": "Semantic Versioning",
         "stack": {
@@ -133,8 +133,49 @@
           "exampleTools": [
             "GitVersion"
           ],
-          "notes": "Use GitVersion to automatically compute SemVer from git history and feed it into assembly/package versions. Configure CI to auto-generate or update CHANGELOG.md from commit messages and git tags. Integrate with release pipeline to automatically version assemblies, NuGet packages, and create release notes.",
-          "verification": "Check that versioning is driven by a SemVer-aware tool (for example, GitVersion) and verify that running the release/versioning step locally or in CI automatically produces the expected version metadata, updates project files, and generates changelog entries from commit history."
+          "notes": "Use GitVersion (or Directory.Build.props) as the single canonical version source, computed from git history, and feed it into assembly/package versions. Configure CI to auto-generate or update CHANGELOG.md from commit messages and git tags. Integrate with the release pipeline to version assemblies, NuGet packages, and publish GitHub releases from the same version.",
+          "optionalFiles": [
+            "GitVersion.yml",
+            "Directory.Build.props",
+            "CHANGELOG.md"
+          ],
+          "requiredFiles": [
+            "*.csproj"
+          ],
+          "requiredScripts": [
+            "release"
+          ],
+          "verification": "Check that versioning is driven by a SemVer-aware tool (for example, GitVersion) and verify that running the release/versioning step locally or in CI produces the expected version metadata, updates project files, and generates changelog entries from commit history."
+        }
+      },
+      {
+        "ciHints": {
+          "azure-devops": {
+            "stage": "release"
+          }
+        },
+        "description": "Use a single CI release pipeline that publishes all artifacts (GitHub releases, packages, containers) from the same canonical version source.",
+        "id": "unified-release-workflow",
+        "label": "Unified Release Workflow",
+        "stack": {
+          "exampleConfigFiles": [
+            "azure-pipelines.yml",
+            ".github/workflows/release.yml"
+          ],
+          "exampleTools": [
+            "GitVersion",
+            "dotnet pack",
+            "dotnet nuget push"
+          ],
+          "notes": "Use a single release pipeline to publish NuGet packages, GitHub releases, and Docker images from the canonical version source (GitVersion or Directory.Build.props).",
+          "optionalFiles": [
+            "GitVersion.yml",
+            "Directory.Build.props"
+          ],
+          "requiredScripts": [
+            "release"
+          ],
+          "verification": "Trigger the release pipeline and confirm all artifacts share the same version number and tag."
         }
       },
       {
@@ -143,10 +184,17 @@
             "stage": "quality"
           }
         },
-        "description": "Enforce structured commit messages such as Conventional Commits.",
+        "description": "Enforce structured commit messages such as Conventional Commits via commit-msg hooks and CI. This is required for deterministic versioning and changelog generation.",
         "id": "commit-linting",
         "label": "Commit Linting",
         "stack": {
+          "anyOfFiles": [
+            "commitlint.config.js",
+            "commitlint.config.cjs",
+            "commitlint.config.mjs",
+            "commitlint.config.json",
+            ".cz.toml"
+          ],
           "exampleConfigFiles": [
             "commitlint.config.*",
             ".cz.toml"
@@ -155,8 +203,11 @@
             "commitlint",
             "commitizen"
           ],
-          "notes": "Document your commit convention and wire up a helper tool so contributors can easily follow it.",
-          "verification": "Create a test commit following the documented commit convention and confirm that any configured commit message checks (local hooks or CI) accept the message."
+          "notes": "Document your Conventional Commit convention and enforce it via commit-msg hooks and CI so release tooling can compute versions deterministically.",
+          "requiredScripts": [
+            "commitlint"
+          ],
+          "verification": "Create a test commit following the documented convention and confirm that commit-msg hooks and CI checks accept it."
         }
       },
       {
@@ -264,7 +315,7 @@
             "stage": "quality"
           }
         },
-        "description": "Use static type checking to catch errors before runtime and enforce strictness on new code.",
+        "description": "Use static type checking to catch errors before runtime and enforce strictness on new code. For JS/TS stacks, require a TypeScript-first policy with strict mode and a CI typecheck step; allow JSDoc/checkJs migration for legacy JS.",
         "id": "type-checking",
         "label": "Type Checking",
         "stack": {
@@ -316,6 +367,88 @@
           "verification": "Dependency lockfile or package reference is present; security scanning is configured."
         }
       },
+      {
+        "ciHints": {
+          "azure-devops": {
+            "stage": "build"
+          }
+        },
+        "description": "Ensure builds are reproducible by pinning dependencies, base images, and tool/runtime versions. Avoid network/time variance and fail when lockfiles drift.",
+        "id": "deterministic-builds",
+        "label": "Deterministic & Hermetic Builds",
+        "stack": {
+          "exampleConfigFiles": [
+            "packages.lock.json",
+            "global.json"
+          ],
+          "exampleTools": [
+            "dotnet restore --locked-mode"
+          ],
+          "notes": "Enable packages.lock.json and use locked restore. Pin SDK versions via global.json and pin base images in Dockerfiles.",
+          "optionalFiles": [
+            "packages.lock.json",
+            "global.json"
+          ],
+          "verification": "packages.lock.json or equivalent lock files exist and restore runs in locked mode. SDK versions are pinned."
+        }
+      },
+      {
+        "ciHints": {
+          "azure-devops": {
+            "stage": "security"
+          }
+        },
+        "description": "Produce SBOMs or provenance metadata, enable secret/code scanning, and sign tags or commits for critical repos.",
+        "id": "provenance-security",
+        "label": "Provenance & Security Metadata",
+        "stack": {
+          "exampleConfigFiles": [
+            ".github/workflows/codeql.yml",
+            ".github/workflows/provenance.yml"
+          ],
+          "exampleTools": [
+            "sbom-tool",
+            "codeql",
+            "gitleaks",
+            "cosign"
+          ],
+          "notes": "Generate SBOM/provenance for NuGet and container artifacts, enable secret scanning, and sign tags/commits for critical repos.",
+          "optionalFiles": [
+            "SECURITY.md",
+            ".github/workflows/codeql.yml"
+          ],
+          "verification": "SBOM/provenance artifacts are published alongside releases, and CI runs secret/code scanning."
+        }
+      },
+      {
+        "ciHints": {
+          "azure-devops": {
+            "stage": "ci"
+          }
+        },
+        "description": "Adopt standard CI templates and config samples to scale across repositories, minimizing bespoke pipeline logic.",
+        "id": "ci-templates-automation",
+        "label": "CI Templates & Automation",
+        "stack": {
+          "anyOfFiles": [
+            ".github/workflows/ci.yml",
+            "azure-pipelines.yml"
+          ],
+          "exampleConfigFiles": [
+            ".github/workflows/ci.yml",
+            "azure-pipelines.yml"
+          ],
+          "exampleTools": [
+            "GitHub Actions reusable workflows",
+            "Azure DevOps templates"
+          ],
+          "notes": "Use shared CI templates for build/test/pack/release stages to standardize across .NET repos.",
+          "requiredScripts": [
+            "ci"
+          ],
+          "verification": "CI pipeline references a shared template or reusable workflow and follows the standard job naming."
+        }
+      },
       {
         "ciHints": {
           "azure-devops": {
@@ -666,5 +799,5 @@
   },
   "stack": "csharp-dotnet",
   "stackLabel": "C# / .NET",
-  "version": 2
+  "version": 3
 }

package/dist/config/standards.csharp-dotnet.github-actions.json

@@ -121,7 +121,7 @@
             "job": "release"
           }
         },
-        "description": "Use MAJOR.MINOR.PATCH versioning with clear rules and automated changelog generation based on commit history.",
+        "description": "Use MAJOR.MINOR.PATCH versioning with clear rules and automated changelog generation based on commit history. Maintain a single canonical version source (for example, package.json or VERSION) that all release artifacts use.",
         "id": "semantic-versioning",
         "label": "Semantic Versioning",
         "stack": {
@@ -133,8 +133,49 @@
           "exampleTools": [
             "GitVersion"
           ],
-          "notes": "Use GitVersion to automatically compute SemVer from git history and feed it into assembly/package versions. Configure CI to auto-generate or update CHANGELOG.md from commit messages and git tags. Integrate with release pipeline to automatically version assemblies, NuGet packages, and create release notes.",
-          "verification": "Check that versioning is driven by a SemVer-aware tool (for example, GitVersion) and verify that running the release/versioning step locally or in CI automatically produces the expected version metadata, updates project files, and generates changelog entries from commit history."
+          "notes": "Use GitVersion (or Directory.Build.props) as the single canonical version source, computed from git history, and feed it into assembly/package versions. Configure CI to auto-generate or update CHANGELOG.md from commit messages and git tags. Integrate with the release pipeline to version assemblies, NuGet packages, and publish GitHub releases from the same version.",
+          "optionalFiles": [
+            "GitVersion.yml",
+            "Directory.Build.props",
+            "CHANGELOG.md"
+          ],
+          "requiredFiles": [
+            "*.csproj"
+          ],
+          "requiredScripts": [
+            "release"
+          ],
+          "verification": "Check that versioning is driven by a SemVer-aware tool (for example, GitVersion) and verify that running the release/versioning step locally or in CI produces the expected version metadata, updates project files, and generates changelog entries from commit history."
+        }
+      },
+      {
+        "ciHints": {
+          "github-actions": {
+            "job": "release"
+          }
+        },
+        "description": "Use a single CI release pipeline that publishes all artifacts (GitHub releases, packages, containers) from the same canonical version source.",
+        "id": "unified-release-workflow",
+        "label": "Unified Release Workflow",
+        "stack": {
+          "exampleConfigFiles": [
+            "azure-pipelines.yml",
+            ".github/workflows/release.yml"
+          ],
+          "exampleTools": [
+            "GitVersion",
+            "dotnet pack",
+            "dotnet nuget push"
+          ],
+          "notes": "Use a single release pipeline to publish NuGet packages, GitHub releases, and Docker images from the canonical version source (GitVersion or Directory.Build.props).",
+          "optionalFiles": [
+            "GitVersion.yml",
+            "Directory.Build.props"
+          ],
+          "requiredScripts": [
+            "release"
+          ],
+          "verification": "Trigger the release pipeline and confirm all artifacts share the same version number and tag."
         }
       },
       {
@@ -143,10 +184,17 @@
             "job": "ci"
           }
         },
-        "description": "Enforce structured commit messages such as Conventional Commits.",
+        "description": "Enforce structured commit messages such as Conventional Commits via commit-msg hooks and CI. This is required for deterministic versioning and changelog generation.",
         "id": "commit-linting",
         "label": "Commit Linting",
         "stack": {
+          "anyOfFiles": [
+            "commitlint.config.js",
+            "commitlint.config.cjs",
+            "commitlint.config.mjs",
+            "commitlint.config.json",
+            ".cz.toml"
+          ],
           "exampleConfigFiles": [
             "commitlint.config.*",
             ".cz.toml"
@@ -155,8 +203,11 @@
             "commitlint",
             "commitizen"
           ],
-          "notes": "Document your commit convention and wire up a helper tool so contributors can easily follow it.",
-          "verification": "Create a test commit following the documented commit convention and confirm that any configured commit message checks (local hooks or CI) accept the message."
+          "notes": "Document your Conventional Commit convention and enforce it via commit-msg hooks and CI so release tooling can compute versions deterministically.",
+          "requiredScripts": [
+            "commitlint"
+          ],
+          "verification": "Create a test commit following the documented convention and confirm that commit-msg hooks and CI checks accept it."
         }
       },
       {
@@ -264,7 +315,7 @@
             "job": "ci"
           }
         },
-        "description": "Use static type checking to catch errors before runtime and enforce strictness on new code.",
+        "description": "Use static type checking to catch errors before runtime and enforce strictness on new code. For JS/TS stacks, require a TypeScript-first policy with strict mode and a CI typecheck step; allow JSDoc/checkJs migration for legacy JS.",
         "id": "type-checking",
         "label": "Type Checking",
         "stack": {
@@ -316,6 +367,88 @@
           "verification": "Dependency lockfile or package reference is present; security scanning is configured."
         }
       },
+      {
+        "ciHints": {
+          "github-actions": {
+            "job": "ci"
+          }
+        },
+        "description": "Ensure builds are reproducible by pinning dependencies, base images, and tool/runtime versions. Avoid network/time variance and fail when lockfiles drift.",
+        "id": "deterministic-builds",
+        "label": "Deterministic & Hermetic Builds",
+        "stack": {
+          "exampleConfigFiles": [
+            "packages.lock.json",
+            "global.json"
+          ],
+          "exampleTools": [
+            "dotnet restore --locked-mode"
+          ],
+          "notes": "Enable packages.lock.json and use locked restore. Pin SDK versions via global.json and pin base images in Dockerfiles.",
+          "optionalFiles": [
+            "packages.lock.json",
+            "global.json"
+          ],
+          "verification": "packages.lock.json or equivalent lock files exist and restore runs in locked mode. SDK versions are pinned."
+        }
+      },
+      {
+        "ciHints": {
+          "github-actions": {
+            "job": "security"
+          }
+        },
+        "description": "Produce SBOMs or provenance metadata, enable secret/code scanning, and sign tags or commits for critical repos.",
+        "id": "provenance-security",
+        "label": "Provenance & Security Metadata",
+        "stack": {
+          "exampleConfigFiles": [
+            ".github/workflows/codeql.yml",
+            ".github/workflows/provenance.yml"
+          ],
+          "exampleTools": [
+            "sbom-tool",
+            "codeql",
+            "gitleaks",
+            "cosign"
+          ],
+          "notes": "Generate SBOM/provenance for NuGet and container artifacts, enable secret scanning, and sign tags/commits for critical repos.",
+          "optionalFiles": [
+            "SECURITY.md",
+            ".github/workflows/codeql.yml"
+          ],
+          "verification": "SBOM/provenance artifacts are published alongside releases, and CI runs secret/code scanning."
+        }
+      },
+      {
+        "ciHints": {
+          "github-actions": {
+            "job": "ci"
+          }
+        },
+        "description": "Adopt standard CI templates and config samples to scale across repositories, minimizing bespoke pipeline logic.",
+        "id": "ci-templates-automation",
+        "label": "CI Templates & Automation",
+        "stack": {
+          "anyOfFiles": [
+            ".github/workflows/ci.yml",
+            "azure-pipelines.yml"
+          ],
+          "exampleConfigFiles": [
+            ".github/workflows/ci.yml",
+            "azure-pipelines.yml"
+          ],
+          "exampleTools": [
+            "GitHub Actions reusable workflows",
+            "Azure DevOps templates"
+          ],
+          "notes": "Use shared CI templates for build/test/pack/release stages to standardize across .NET repos.",
+          "requiredScripts": [
+            "ci"
+          ],
+          "verification": "CI pipeline references a shared template or reusable workflow and follows the standard job naming."
+        }
+      },
       {
         "ciHints": {
           "github-actions": {
@@ -666,5 +799,5 @@
   },
   "stack": "csharp-dotnet",
   "stackLabel": "C# / .NET",
-  "version": 2
+  "version": 3
 }

package/dist/config/standards.csharp-dotnet.json

@@ -136,7 +136,7 @@
             "job": "release"
           }
         },
-        "description": "Use MAJOR.MINOR.PATCH versioning with clear rules and automated changelog generation based on commit history.",
+        "description": "Use MAJOR.MINOR.PATCH versioning with clear rules and automated changelog generation based on commit history. Maintain a single canonical version source (for example, package.json or VERSION) that all release artifacts use.",
         "id": "semantic-versioning",
         "label": "Semantic Versioning",
         "stack": {
@@ -148,8 +148,52 @@
           "exampleTools": [
             "GitVersion"
           ],
-          "notes": "Use GitVersion to automatically compute SemVer from git history and feed it into assembly/package versions. Configure CI to auto-generate or update CHANGELOG.md from commit messages and git tags. Integrate with release pipeline to automatically version assemblies, NuGet packages, and create release notes.",
-          "verification": "Check that versioning is driven by a SemVer-aware tool (for example, GitVersion) and verify that running the release/versioning step locally or in CI automatically produces the expected version metadata, updates project files, and generates changelog entries from commit history."
+          "notes": "Use GitVersion (or Directory.Build.props) as the single canonical version source, computed from git history, and feed it into assembly/package versions. Configure CI to auto-generate or update CHANGELOG.md from commit messages and git tags. Integrate with the release pipeline to version assemblies, NuGet packages, and publish GitHub releases from the same version.",
+          "optionalFiles": [
+            "GitVersion.yml",
+            "Directory.Build.props",
+            "CHANGELOG.md"
+          ],
+          "requiredFiles": [
+            "*.csproj"
+          ],
+          "requiredScripts": [
+            "release"
+          ],
+          "verification": "Check that versioning is driven by a SemVer-aware tool (for example, GitVersion) and verify that running the release/versioning step locally or in CI produces the expected version metadata, updates project files, and generates changelog entries from commit history."
+        }
+      },
+      {
+        "ciHints": {
+          "azure-devops": {
+            "stage": "release"
+          },
+          "github-actions": {
+            "job": "release"
+          }
+        },
+        "description": "Use a single CI release pipeline that publishes all artifacts (GitHub releases, packages, containers) from the same canonical version source.",
+        "id": "unified-release-workflow",
+        "label": "Unified Release Workflow",
+        "stack": {
+          "exampleConfigFiles": [
+            "azure-pipelines.yml",
+            ".github/workflows/release.yml"
+          ],
+          "exampleTools": [
+            "GitVersion",
+            "dotnet pack",
+            "dotnet nuget push"
+          ],
+          "notes": "Use a single release pipeline to publish NuGet packages, GitHub releases, and Docker images from the canonical version source (GitVersion or Directory.Build.props).",
+          "optionalFiles": [
+            "GitVersion.yml",
+            "Directory.Build.props"
+          ],
+          "requiredScripts": [
+            "release"
+          ],
+          "verification": "Trigger the release pipeline and confirm all artifacts share the same version number and tag."
         }
       },
       {
@@ -161,10 +205,17 @@
             "job": "ci"
           }
         },
-        "description": "Enforce structured commit messages such as Conventional Commits.",
+        "description": "Enforce structured commit messages such as Conventional Commits via commit-msg hooks and CI. This is required for deterministic versioning and changelog generation.",
         "id": "commit-linting",
         "label": "Commit Linting",
         "stack": {
+          "anyOfFiles": [
+            "commitlint.config.js",
+            "commitlint.config.cjs",
+            "commitlint.config.mjs",
+            "commitlint.config.json",
+            ".cz.toml"
+          ],
           "exampleConfigFiles": [
             "commitlint.config.*",
             ".cz.toml"
@@ -173,8 +224,11 @@
             "commitlint",
             "commitizen"
           ],
-          "notes": "Document your commit convention and wire up a helper tool so contributors can easily follow it.",
-          "verification": "Create a test commit following the documented commit convention and confirm that any configured commit message checks (local hooks or CI) accept the message."
+          "notes": "Document your Conventional Commit convention and enforce it via commit-msg hooks and CI so release tooling can compute versions deterministically.",
+          "requiredScripts": [
+            "commitlint"
+          ],
+          "verification": "Create a test commit following the documented convention and confirm that commit-msg hooks and CI checks accept it."
         }
       },
       {
@@ -297,7 +351,7 @@
             "job": "ci"
           }
         },
-        "description": "Use static type checking to catch errors before runtime and enforce strictness on new code.",
+        "description": "Use static type checking to catch errors before runtime and enforce strictness on new code. For JS/TS stacks, require a TypeScript-first policy with strict mode and a CI typecheck step; allow JSDoc/checkJs migration for legacy JS.",
         "id": "type-checking",
         "label": "Type Checking",
         "stack": {
@@ -352,6 +406,97 @@
           "verification": "Dependency lockfile or package reference is present; security scanning is configured."
         }
       },
+      {
+        "ciHints": {
+          "azure-devops": {
+            "stage": "build"
+          },
+          "github-actions": {
+            "job": "ci"
+          }
+        },
+        "description": "Ensure builds are reproducible by pinning dependencies, base images, and tool/runtime versions. Avoid network/time variance and fail when lockfiles drift.",
+        "id": "deterministic-builds",
+        "label": "Deterministic & Hermetic Builds",
+        "stack": {
+          "exampleConfigFiles": [
+            "packages.lock.json",
+            "global.json"
+          ],
+          "exampleTools": [
+            "dotnet restore --locked-mode"
+          ],
+          "notes": "Enable packages.lock.json and use locked restore. Pin SDK versions via global.json and pin base images in Dockerfiles.",
+          "optionalFiles": [
+            "packages.lock.json",
+            "global.json"
+          ],
+          "verification": "packages.lock.json or equivalent lock files exist and restore runs in locked mode. SDK versions are pinned."
+        }
+      },
+      {
+        "ciHints": {
+          "azure-devops": {
+            "stage": "security"
+          },
+          "github-actions": {
+            "job": "security"
+          }
+        },
+        "description": "Produce SBOMs or provenance metadata, enable secret/code scanning, and sign tags or commits for critical repos.",
+        "id": "provenance-security",
+        "label": "Provenance & Security Metadata",
+        "stack": {
+          "exampleConfigFiles": [
+            ".github/workflows/codeql.yml",
+            ".github/workflows/provenance.yml"
+          ],
+          "exampleTools": [
+            "sbom-tool",
+            "codeql",
+            "gitleaks",
+            "cosign"
+          ],
+          "notes": "Generate SBOM/provenance for NuGet and container artifacts, enable secret scanning, and sign tags/commits for critical repos.",
+          "optionalFiles": [
+            "SECURITY.md",
+            ".github/workflows/codeql.yml"
+          ],
+          "verification": "SBOM/provenance artifacts are published alongside releases, and CI runs secret/code scanning."
+        }
+      },
+      {
+        "ciHints": {
+          "azure-devops": {
+            "stage": "ci"
+          },
+          "github-actions": {
+            "job": "ci"
+          }
+        },
+        "description": "Adopt standard CI templates and config samples to scale across repositories, minimizing bespoke pipeline logic.",
+        "id": "ci-templates-automation",
+        "label": "CI Templates & Automation",
+        "stack": {
+          "anyOfFiles": [
+            ".github/workflows/ci.yml",
+            "azure-pipelines.yml"
+          ],
+          "exampleConfigFiles": [
+            ".github/workflows/ci.yml",
+            "azure-pipelines.yml"
+          ],
+          "exampleTools": [
+            "GitHub Actions reusable workflows",
+            "Azure DevOps templates"
+          ],
+          "notes": "Use shared CI templates for build/test/pack/release stages to standardize across .NET repos.",
+          "requiredScripts": [
+            "ci"
+          ],
+          "verification": "CI pipeline references a shared template or reusable workflow and follows the standard job naming."
+        }
+      },
       {
         "ciHints": {
           "azure-devops": {
@@ -735,5 +880,5 @@
   },
   "stack": "csharp-dotnet",
   "stackLabel": "C# / .NET",
-  "version": 2
+  "version": 3
 }