@oddessentials/repo-standards 2.1.0 → 3.1.0

package/dist/config/standards.python.azure-devops.json

@@ -125,7 +125,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": {
@@ -139,8 +139,49 @@
             "setuptools_scm",
             "towncrier"
           ],
-          "notes": "Automate version bumping and changelog generation using setuptools_scm (git-tag based) or bumpversion with towncrier for changelog fragments. Configure CI to automatically update version in pyproject.toml, generate/update CHANGELOG.md from commit messages or changelog fragments, and create git tags. Maintain a single source of truth for versioning.",
-          "verification": "Check that the package version in pyproject or setup configuration follows SemVer and verify that the configured tool (for example, setuptools_scm or bumpversion) automatically computes or bumps the version and generates changelog entries from commit history or fragments."
+          "notes": "Automate version bumping and changelog generation using setuptools_scm (git-tag based) or bumpversion with towncrier for changelog fragments. Keep pyproject.toml (or VERSION) as the single canonical version source, and have CI publish GitHub/PyPI/Docker artifacts from that same version.",
+          "optionalFiles": [
+            "VERSION",
+            "CHANGELOG.md"
+          ],
+          "requiredFiles": [
+            "pyproject.toml"
+          ],
+          "requiredScripts": [
+            "release"
+          ],
+          "verification": "Check that the canonical version in pyproject.toml or VERSION follows SemVer and verify that the configured tool (for example, setuptools_scm or bumpversion) computes or bumps the version and generates changelog entries from commit history or fragments."
+        }
+      },
+      {
+        "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": [
+            ".github/workflows/release.yml",
+            "azure-pipelines.yml"
+          ],
+          "exampleTools": [
+            "setuptools_scm",
+            "twine",
+            "build",
+            "docker buildx"
+          ],
+          "notes": "Use a single release pipeline to publish PyPI packages, GitHub releases, and Docker images from the canonical version source (pyproject.toml or VERSION).",
+          "optionalFiles": [
+            "CHANGELOG.md",
+            "VERSION"
+          ],
+          "requiredScripts": [
+            "release"
+          ],
+          "verification": "Trigger the release pipeline and confirm all artifacts share the same version number and tag."
         }
       },
       {
@@ -149,10 +190,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": [
+            ".cz.toml",
+            "commitlint.config.js",
+            "commitlint.config.cjs",
+            "commitlint.config.mjs",
+            "commitlint.config.json"
+          ],
           "exampleConfigFiles": [
             ".cz.toml",
             "pyproject.toml"
@@ -160,8 +208,11 @@
           "exampleTools": [
             "commitizen"
           ],
-          "notes": "Standardize commit messages using commitizen or a similar helper and document the required types and scopes.",
-          "verification": "Use the configured commit helper (for example, commitizen) or hooks to create a test commit and confirm that non-conforming messages are rejected while valid ones are accepted."
+          "notes": "Standardize Conventional Commits using commitizen or commitlint with commit-msg hooks plus CI so changelog generation is deterministic.",
+          "requiredScripts": [
+            "commitlint"
+          ],
+          "verification": "Use the configured commit helper or hooks to create a test commit and confirm that non-conforming messages are rejected locally and in CI."
         }
       },
       {
@@ -271,7 +322,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": {
@@ -296,6 +347,9 @@
           "requiredFiles": [
             "pyproject.toml"
           ],
+          "requiredScripts": [
+            "typecheck"
+          ],
           "verification": "pyproject.toml (or mypy.ini) signals that mypy configuration is available for the repository."
         }
       },
@@ -327,6 +381,97 @@
           "verification": "Dependency lockfile is present; security scanning is configured in CI or project tooling."
         }
       },
+      {
+        "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": {
+          "anyOfFiles": [
+            "requirements.txt",
+            "poetry.lock",
+            "Pipfile.lock"
+          ],
+          "exampleConfigFiles": [
+            "requirements.txt",
+            "poetry.lock",
+            "Pipfile.lock"
+          ],
+          "exampleTools": [
+            "pip-tools",
+            "poetry",
+            "uv"
+          ],
+          "notes": "Use pinned lockfiles (requirements.txt or poetry.lock) and pin Python version (.python-version or tool-versions). Avoid non-deterministic installs in CI.",
+          "optionalFiles": [
+            ".python-version",
+            ".tool-versions"
+          ],
+          "verification": "Lockfile is present and CI installs with pinned versions only. Python runtime is 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": [
+            "cyclonedx-python",
+            "syft",
+            "codeql",
+            "gitleaks",
+            "cosign"
+          ],
+          "notes": "Generate SBOM/provenance for PyPI 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 lint/test/typecheck/release stages to standardize across Python repos.",
+          "requiredScripts": [
+            "ci"
+          ],
+          "verification": "CI pipeline references a shared template or reusable workflow and follows the standard job naming."
+        }
+      },
       {
         "ciHints": {
           "azure-devops": {

package/dist/config/standards.python.github-actions.json

@@ -125,7 +125,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": {
@@ -139,8 +139,49 @@
             "setuptools_scm",
             "towncrier"
           ],
-          "notes": "Automate version bumping and changelog generation using setuptools_scm (git-tag based) or bumpversion with towncrier for changelog fragments. Configure CI to automatically update version in pyproject.toml, generate/update CHANGELOG.md from commit messages or changelog fragments, and create git tags. Maintain a single source of truth for versioning.",
-          "verification": "Check that the package version in pyproject or setup configuration follows SemVer and verify that the configured tool (for example, setuptools_scm or bumpversion) automatically computes or bumps the version and generates changelog entries from commit history or fragments."
+          "notes": "Automate version bumping and changelog generation using setuptools_scm (git-tag based) or bumpversion with towncrier for changelog fragments. Keep pyproject.toml (or VERSION) as the single canonical version source, and have CI publish GitHub/PyPI/Docker artifacts from that same version.",
+          "optionalFiles": [
+            "VERSION",
+            "CHANGELOG.md"
+          ],
+          "requiredFiles": [
+            "pyproject.toml"
+          ],
+          "requiredScripts": [
+            "release"
+          ],
+          "verification": "Check that the canonical version in pyproject.toml or VERSION follows SemVer and verify that the configured tool (for example, setuptools_scm or bumpversion) computes or bumps the version and generates changelog entries from commit history or fragments."
+        }
+      },
+      {
+        "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": [
+            ".github/workflows/release.yml",
+            "azure-pipelines.yml"
+          ],
+          "exampleTools": [
+            "setuptools_scm",
+            "twine",
+            "build",
+            "docker buildx"
+          ],
+          "notes": "Use a single release pipeline to publish PyPI packages, GitHub releases, and Docker images from the canonical version source (pyproject.toml or VERSION).",
+          "optionalFiles": [
+            "CHANGELOG.md",
+            "VERSION"
+          ],
+          "requiredScripts": [
+            "release"
+          ],
+          "verification": "Trigger the release pipeline and confirm all artifacts share the same version number and tag."
         }
       },
       {
@@ -149,10 +190,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": [
+            ".cz.toml",
+            "commitlint.config.js",
+            "commitlint.config.cjs",
+            "commitlint.config.mjs",
+            "commitlint.config.json"
+          ],
           "exampleConfigFiles": [
             ".cz.toml",
             "pyproject.toml"
@@ -160,8 +208,11 @@
           "exampleTools": [
             "commitizen"
           ],
-          "notes": "Standardize commit messages using commitizen or a similar helper and document the required types and scopes.",
-          "verification": "Use the configured commit helper (for example, commitizen) or hooks to create a test commit and confirm that non-conforming messages are rejected while valid ones are accepted."
+          "notes": "Standardize Conventional Commits using commitizen or commitlint with commit-msg hooks plus CI so changelog generation is deterministic.",
+          "requiredScripts": [
+            "commitlint"
+          ],
+          "verification": "Use the configured commit helper or hooks to create a test commit and confirm that non-conforming messages are rejected locally and in CI."
         }
       },
       {
@@ -271,7 +322,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": {
@@ -296,6 +347,9 @@
           "requiredFiles": [
             "pyproject.toml"
           ],
+          "requiredScripts": [
+            "typecheck"
+          ],
           "verification": "pyproject.toml (or mypy.ini) signals that mypy configuration is available for the repository."
         }
       },
@@ -327,6 +381,97 @@
           "verification": "Dependency lockfile is present; security scanning is configured in CI or project tooling."
         }
       },
+      {
+        "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": {
+          "anyOfFiles": [
+            "requirements.txt",
+            "poetry.lock",
+            "Pipfile.lock"
+          ],
+          "exampleConfigFiles": [
+            "requirements.txt",
+            "poetry.lock",
+            "Pipfile.lock"
+          ],
+          "exampleTools": [
+            "pip-tools",
+            "poetry",
+            "uv"
+          ],
+          "notes": "Use pinned lockfiles (requirements.txt or poetry.lock) and pin Python version (.python-version or tool-versions). Avoid non-deterministic installs in CI.",
+          "optionalFiles": [
+            ".python-version",
+            ".tool-versions"
+          ],
+          "verification": "Lockfile is present and CI installs with pinned versions only. Python runtime is 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": [
+            "cyclonedx-python",
+            "syft",
+            "codeql",
+            "gitleaks",
+            "cosign"
+          ],
+          "notes": "Generate SBOM/provenance for PyPI 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 lint/test/typecheck/release stages to standardize across Python repos.",
+          "requiredScripts": [
+            "ci"
+          ],
+          "verification": "CI pipeline references a shared template or reusable workflow and follows the standard job naming."
+        }
+      },
       {
         "ciHints": {
           "github-actions": {

package/dist/config/standards.python.json

@@ -140,7 +140,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": {
@@ -154,8 +154,52 @@
             "setuptools_scm",
             "towncrier"
           ],
-          "notes": "Automate version bumping and changelog generation using setuptools_scm (git-tag based) or bumpversion with towncrier for changelog fragments. Configure CI to automatically update version in pyproject.toml, generate/update CHANGELOG.md from commit messages or changelog fragments, and create git tags. Maintain a single source of truth for versioning.",
-          "verification": "Check that the package version in pyproject or setup configuration follows SemVer and verify that the configured tool (for example, setuptools_scm or bumpversion) automatically computes or bumps the version and generates changelog entries from commit history or fragments."
+          "notes": "Automate version bumping and changelog generation using setuptools_scm (git-tag based) or bumpversion with towncrier for changelog fragments. Keep pyproject.toml (or VERSION) as the single canonical version source, and have CI publish GitHub/PyPI/Docker artifacts from that same version.",
+          "optionalFiles": [
+            "VERSION",
+            "CHANGELOG.md"
+          ],
+          "requiredFiles": [
+            "pyproject.toml"
+          ],
+          "requiredScripts": [
+            "release"
+          ],
+          "verification": "Check that the canonical version in pyproject.toml or VERSION follows SemVer and verify that the configured tool (for example, setuptools_scm or bumpversion) computes or bumps the version and generates changelog entries from commit history or fragments."
+        }
+      },
+      {
+        "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": [
+            ".github/workflows/release.yml",
+            "azure-pipelines.yml"
+          ],
+          "exampleTools": [
+            "setuptools_scm",
+            "twine",
+            "build",
+            "docker buildx"
+          ],
+          "notes": "Use a single release pipeline to publish PyPI packages, GitHub releases, and Docker images from the canonical version source (pyproject.toml or VERSION).",
+          "optionalFiles": [
+            "CHANGELOG.md",
+            "VERSION"
+          ],
+          "requiredScripts": [
+            "release"
+          ],
+          "verification": "Trigger the release pipeline and confirm all artifacts share the same version number and tag."
         }
       },
       {
@@ -167,10 +211,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": [
+            ".cz.toml",
+            "commitlint.config.js",
+            "commitlint.config.cjs",
+            "commitlint.config.mjs",
+            "commitlint.config.json"
+          ],
           "exampleConfigFiles": [
             ".cz.toml",
             "pyproject.toml"
@@ -178,8 +229,11 @@
           "exampleTools": [
             "commitizen"
           ],
-          "notes": "Standardize commit messages using commitizen or a similar helper and document the required types and scopes.",
-          "verification": "Use the configured commit helper (for example, commitizen) or hooks to create a test commit and confirm that non-conforming messages are rejected while valid ones are accepted."
+          "notes": "Standardize Conventional Commits using commitizen or commitlint with commit-msg hooks plus CI so changelog generation is deterministic.",
+          "requiredScripts": [
+            "commitlint"
+          ],
+          "verification": "Use the configured commit helper or hooks to create a test commit and confirm that non-conforming messages are rejected locally and in CI."
         }
       },
       {
@@ -304,7 +358,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": {
@@ -329,6 +383,9 @@
           "requiredFiles": [
             "pyproject.toml"
           ],
+          "requiredScripts": [
+            "typecheck"
+          ],
           "verification": "pyproject.toml (or mypy.ini) signals that mypy configuration is available for the repository."
         }
       },
@@ -363,6 +420,106 @@
           "verification": "Dependency lockfile is present; security scanning is configured in CI or project tooling."
         }
       },
+      {
+        "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": {
+          "anyOfFiles": [
+            "requirements.txt",
+            "poetry.lock",
+            "Pipfile.lock"
+          ],
+          "exampleConfigFiles": [
+            "requirements.txt",
+            "poetry.lock",
+            "Pipfile.lock"
+          ],
+          "exampleTools": [
+            "pip-tools",
+            "poetry",
+            "uv"
+          ],
+          "notes": "Use pinned lockfiles (requirements.txt or poetry.lock) and pin Python version (.python-version or tool-versions). Avoid non-deterministic installs in CI.",
+          "optionalFiles": [
+            ".python-version",
+            ".tool-versions"
+          ],
+          "verification": "Lockfile is present and CI installs with pinned versions only. Python runtime is 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": [
+            "cyclonedx-python",
+            "syft",
+            "codeql",
+            "gitleaks",
+            "cosign"
+          ],
+          "notes": "Generate SBOM/provenance for PyPI 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 lint/test/typecheck/release stages to standardize across Python repos.",
+          "requiredScripts": [
+            "ci"
+          ],
+          "verification": "CI pipeline references a shared template or reusable workflow and follows the standard job naming."
+        }
+      },
       {
         "ciHints": {
           "azure-devops": {