@oddessentials/repo-standards 1.0.1

package/dist/config/standards.json

@@ -0,0 +1,1351 @@
+{
+  "checklist": {
+    "core": [
+      {
+        "appliesTo": {
+          "stacks": [
+            "typescript-js",
+            "csharp-dotnet",
+            "python"
+          ]
+        },
+        "ciHints": {
+          "azure-devops": {
+            "stage": "quality"
+          },
+          "github-actions": {
+            "job": "ci"
+          }
+        },
+        "description": "Maintain proper .gitignore and .dockerignore files to prevent committing secrets, build artifacts, or unnecessary files.",
+        "id": "gitignore-and-dockerignore",
+        "label": "Git and Docker Ignore Files",
+        "stackHints": {
+          "csharp-dotnet": {
+            "exampleConfigFiles": [
+              ".gitignore",
+              ".dockerignore"
+            ],
+            "notes": "Use the official github/gitignore VisualStudio/.NET template. .dockerignore must exclude bin/, obj/, .vs/, *.user, and similar local/build artifacts.",
+            "optionalFiles": [
+              ".dockerignore"
+            ],
+            "requiredFiles": [
+              ".gitignore"
+            ],
+            "verification": ".gitignore must exist; .dockerignore is recommended when containerizing or using Docker workflows."
+          },
+          "python": {
+            "exampleConfigFiles": [
+              ".gitignore",
+              ".dockerignore"
+            ],
+            "notes": "Use the official github/gitignore Python template. Include **pycache**, .venv/, .pytest_cache, .env, and similar local-only files. .dockerignore must exclude .git, virtual environments, and caches.",
+            "optionalFiles": [
+              ".dockerignore"
+            ],
+            "requiredFiles": [
+              ".gitignore"
+            ],
+            "verification": ".gitignore must exist; .dockerignore is recommended when containerizing or using Docker workflows."
+          },
+          "typescript-js": {
+            "exampleConfigFiles": [
+              ".gitignore",
+              ".dockerignore"
+            ],
+            "notes": "Use the official github/gitignore Node template as a base and add .env*, node_modules, dist/, coverage/, *.log, npm-debug.log*, etc. .dockerignore must exclude node_modules, .git, and local build output.",
+            "optionalFiles": [
+              ".dockerignore"
+            ],
+            "requiredFiles": [
+              ".gitignore"
+            ],
+            "verification": ".gitignore must exist; .dockerignore is recommended when containerizing or using Docker workflows."
+          }
+        }
+      },
+      {
+        "appliesTo": {
+          "stacks": [
+            "typescript-js",
+            "csharp-dotnet",
+            "python"
+          ]
+        },
+        "ciHints": {
+          "azure-devops": {
+            "stage": "quality"
+          },
+          "github-actions": {
+            "job": "ci"
+          }
+        },
+        "description": "Run static code linting to enforce consistency and catch common issues early.",
+        "id": "linting",
+        "label": "Linting",
+        "stackHints": {
+          "csharp-dotnet": {
+            "exampleConfigFiles": [
+              ".editorconfig",
+              "Directory.Build.props"
+            ],
+            "exampleTools": [
+              "Roslyn analyzers",
+              "StyleCop"
+            ],
+            "notes": "Enable analyzers or style rules for the solution and review warnings regularly; enforce stricter rules on new code.",
+            "optionalFiles": [
+              "Directory.Build.props"
+            ],
+            "requiredFiles": [
+              ".editorconfig"
+            ],
+            "requiredScripts": [
+              "lint"
+            ],
+            "verification": ".editorconfig must exist to drive the .NET formatting and analysis tooling."
+          },
+          "python": {
+            "exampleConfigFiles": [
+              "pyproject.toml",
+              ".flake8"
+            ],
+            "exampleTools": [
+              "ruff",
+              "flake8"
+            ],
+            "notes": "Configure a primary linter (such as ruff) and keep rules focused on catching real issues without overwhelming developers.",
+            "optionalFiles": [
+              "ruff.toml",
+              ".flake8"
+            ],
+            "requiredFiles": [
+              "pyproject.toml"
+            ],
+            "requiredScripts": [
+              "lint"
+            ],
+            "verification": "pyproject.toml (or ruff.toml / .flake8) signals that linting tools are configured for the repository."
+          },
+          "typescript-js": {
+            "exampleConfigFiles": [
+              ".eslintrc.*"
+            ],
+            "exampleTools": [
+              "eslint"
+            ],
+            "notes": "Treat new lint errors as CI failures; keep existing issues as warnings until addressed.",
+            "optionalFiles": [
+              ".eslintrc.js",
+              ".eslintrc.cjs",
+              ".eslintrc.json",
+              ".eslintrc.yaml",
+              ".prettierrc",
+              "prettier.config.js",
+              "prettier.config.cjs",
+              "prettier.config.json",
+              "prettier.config.yaml"
+            ],
+            "requiredFiles": [
+              "eslint.config.js"
+            ],
+            "requiredScripts": [
+              "lint"
+            ],
+            "verification": "Presence of eslint.config.js (or any .eslintrc* file) indicates linting is enforced for the repository."
+          }
+        }
+      },
+      {
+        "appliesTo": {
+          "stacks": [
+            "typescript-js",
+            "csharp-dotnet",
+            "python"
+          ]
+        },
+        "ciHints": {
+          "azure-devops": {
+            "stage": "test"
+          },
+          "github-actions": {
+            "job": "ci"
+          }
+        },
+        "description": "Provide a deterministic unit test framework with a single command to run all tests.",
+        "id": "unit-test-runner",
+        "label": "Unit Test Runner",
+        "stackHints": {
+          "csharp-dotnet": {
+            "exampleConfigFiles": [
+              "*.Tests.csproj"
+            ],
+            "exampleTools": [
+              "xUnit",
+              "NUnit",
+              "MSTest"
+            ],
+            "notes": "Group unit tests into dedicated test projects and keep them independent from external services.",
+            "optionalFiles": [
+              "*.Tests.csproj"
+            ],
+            "verification": "Test projects are present in the solution; test configuration is defined."
+          },
+          "python": {
+            "exampleConfigFiles": [
+              "pytest.ini",
+              "pyproject.toml"
+            ],
+            "exampleTools": [
+              "pytest"
+            ],
+            "notes": "Organize unit tests under a tests/ directory and avoid real network or database calls in this layer.",
+            "optionalFiles": [
+              "pytest.ini",
+              "pyproject.toml",
+              "tests/"
+            ],
+            "requiredScripts": [
+              "test"
+            ],
+            "verification": "Test framework configuration is present; tests/ directory or pytest configuration exists."
+          },
+          "typescript-js": {
+            "exampleConfigFiles": [
+              "jest.config.*"
+            ],
+            "exampleTools": [
+              "jest"
+            ],
+            "notes": "Keep unit tests fast and deterministic; move slow or flaky tests into integration or E2E suites.",
+            "optionalFiles": [
+              "jest.config.js",
+              "jest.config.ts",
+              "vitest.config.js",
+              "vitest.config.ts"
+            ],
+            "requiredScripts": [
+              "test"
+            ],
+            "verification": "Test framework configuration is present; test script is defined in package.json."
+          }
+        }
+      },
+      {
+        "appliesTo": {
+          "stacks": [
+            "typescript-js",
+            "csharp-dotnet",
+            "python"
+          ]
+        },
+        "ciHints": {
+          "azure-devops": {
+            "stage": "build"
+          },
+          "github-actions": {
+            "job": "ci"
+          }
+        },
+        "description": "Provide a Dockerfile and, if applicable, a docker-compose file for local dev and CI parity.",
+        "id": "containerization",
+        "label": "Containerization (Docker / Docker Compose)",
+        "stackHints": {
+          "csharp-dotnet": {
+            "exampleConfigFiles": [
+              "Dockerfile",
+              "docker-compose.yml"
+            ],
+            "exampleTools": [],
+            "notes": "Use multi-stage builds for .NET publish output and pin the SDK/runtime image versions to match CI.",
+            "optionalFiles": [
+              "docker-compose.yml"
+            ],
+            "requiredFiles": [
+              "Dockerfile"
+            ],
+            "verification": "Dockerfile must be present; docker-compose.yml is optional and indicates orchestration usage."
+          },
+          "python": {
+            "exampleConfigFiles": [
+              "Dockerfile",
+              "docker-compose.yml"
+            ],
+            "exampleTools": [],
+            "notes": "Choose a slim Python base image, pin the version, and clearly document how to start the service in a container.",
+            "optionalFiles": [
+              "docker-compose.yml"
+            ],
+            "requiredFiles": [
+              "Dockerfile"
+            ],
+            "verification": "Dockerfile must be present; docker-compose.yml is optional and indicates orchestration usage."
+          },
+          "typescript-js": {
+            "exampleConfigFiles": [
+              "Dockerfile",
+              "docker-compose.yml"
+            ],
+            "exampleTools": [],
+            "notes": "Use multi-stage builds and pin Node.js and base image versions in the Dockerfile to match CI (e.g., node:22-alpine).",
+            "optionalFiles": [
+              "docker-compose.yml"
+            ],
+            "requiredFiles": [
+              "Dockerfile"
+            ],
+            "verification": "Dockerfile must be present; docker-compose.yml is optional and indicates orchestration usage."
+          }
+        }
+      },
+      {
+        "appliesTo": {
+          "stacks": [
+            "typescript-js",
+            "csharp-dotnet",
+            "python"
+          ]
+        },
+        "ciHints": {
+          "azure-devops": {
+            "stage": "release"
+          },
+          "github-actions": {
+            "job": "release"
+          }
+        },
+        "description": "Use MAJOR.MINOR.PATCH versioning with clear rules and automated changelog generation based on commit history.",
+        "id": "semantic-versioning",
+        "label": "Semantic Versioning",
+        "stackHints": {
+          "csharp-dotnet": {
+            "exampleConfigFiles": [
+              "GitVersion.yml",
+              "*.csproj",
+              "CHANGELOG.md"
+            ],
+            "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."
+          },
+          "python": {
+            "exampleConfigFiles": [
+              "pyproject.toml",
+              "setup.cfg",
+              "CHANGELOG.md"
+            ],
+            "exampleTools": [
+              "bumpversion",
+              "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."
+          },
+          "typescript-js": {
+            "exampleConfigFiles": [
+              ".releaserc",
+              "package.json",
+              "CHANGELOG.md"
+            ],
+            "exampleTools": [
+              "semantic-release",
+              "standard-version"
+            ],
+            "notes": "Automate version bumping and changelog generation from Conventional Commits using semantic-release or standard-version. Configure CI to automatically bump package.json version, generate/update CHANGELOG.md, create git tags, and publish release artifacts. Protect release branches and ensure release tooling only runs there.",
+            "verification": "Check that the version field follows SemVer, and trigger the configured release workflow (for example, a dry run of semantic-release or standard-version) to confirm it automatically generates the expected next version, updates package.json, and creates/updates CHANGELOG.md with commit-based entries."
+          }
+        }
+      },
+      {
+        "appliesTo": {
+          "stacks": [
+            "typescript-js",
+            "csharp-dotnet",
+            "python"
+          ]
+        },
+        "ciHints": {
+          "azure-devops": {
+            "stage": "quality"
+          },
+          "github-actions": {
+            "job": "ci"
+          }
+        },
+        "description": "Enforce structured commit messages such as Conventional Commits.",
+        "id": "commit-linting",
+        "label": "Commit Linting",
+        "stackHints": {
+          "csharp-dotnet": {
+            "exampleConfigFiles": [
+              "commitlint.config.*",
+              ".cz.toml"
+            ],
+            "exampleTools": [
+              "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."
+          },
+          "python": {
+            "exampleConfigFiles": [
+              ".cz.toml",
+              "pyproject.toml"
+            ],
+            "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."
+          },
+          "typescript-js": {
+            "exampleConfigFiles": [
+              "commitlint.config.*"
+            ],
+            "exampleTools": [
+              "@commitlint/cli",
+              "@commitlint/config-conventional"
+            ],
+            "notes": "Enforce commit message format via commit-msg hooks (e.g., Husky) before CI.",
+            "verification": "Create a test commit using the documented convention and ensure the commit message passes the configured commit linting or wizard (for example, commitlint or commitizen)."
+          }
+        }
+      },
+      {
+        "appliesTo": {
+          "stacks": [
+            "typescript-js",
+            "csharp-dotnet",
+            "python"
+          ]
+        },
+        "ciHints": {
+          "azure-devops": {
+            "stage": "test"
+          },
+          "github-actions": {
+            "job": "ci"
+          }
+        },
+        "description": "Generate readable unit test and coverage reports and enforce a minimum coverage threshold (around 80%) for new or changed code.",
+        "id": "unit-test-reporter",
+        "label": "Unit Test Reporter / Coverage",
+        "stackHints": {
+          "csharp-dotnet": {
+            "exampleConfigFiles": [
+              "*.csproj"
+            ],
+            "exampleTools": [
+              "coverlet",
+              "ReportGenerator"
+            ],
+            "notes": "Enable coverage collection for test projects and publish reports in a human-friendly format from CI.",
+            "verification": "Run the test suite with coverage enabled (for example, using coverlet or a similar tool) and verify that coverage reports are generated and used in CI to monitor thresholds."
+          },
+          "python": {
+            "exampleConfigFiles": [
+              "pytest.ini",
+              "pyproject.toml"
+            ],
+            "exampleTools": [
+              "pytest",
+              "pytest-cov",
+              "coverage.py"
+            ],
+            "notes": "Configure coverage reporting for your test suite and surface summary metrics in CI.",
+            "verification": "Run the unit tests with coverage (for example, pytest with pytest-cov) and confirm that coverage reports are generated and referenced in CI to enforce or track thresholds."
+          },
+          "typescript-js": {
+            "exampleConfigFiles": [
+              "jest.config.*"
+            ],
+            "exampleTools": [
+              "jest",
+              "nyc"
+            ],
+            "notes": "Collect coverage in lcov or similar format; use diff coverage so legacy gaps are visible but non-blocking.",
+            "verification": "Run the unit tests with coverage enabled and confirm that a coverage report is produced and that the configured threshold (around 80%) is enforced for new changes."
+          }
+        }
+      },
+      {
+        "appliesTo": {
+          "stacks": [
+            "typescript-js",
+            "csharp-dotnet",
+            "python"
+          ]
+        },
+        "ciHints": {
+          "azure-devops": {
+            "stage": "ci"
+          },
+          "github-actions": {
+            "job": "ci"
+          }
+        },
+        "description": "Single CI pipeline that runs linting, formatting, type checking, tests, coverage, build, and containerization.",
+        "id": "ci-quality-gates",
+        "label": "CI Quality Gates",
+        "stackHints": {
+          "csharp-dotnet": {
+            "exampleConfigFiles": [
+              ".github/workflows/*",
+              "azure-pipelines.yml"
+            ],
+            "exampleTools": [],
+            "notes": "Ensure CI runs analyzers, tests, build, and packaging or container checks before changes can be merged.",
+            "verification": "Open the CI configuration and verify there is a job or stage that runs analyzers, tests, build, and any required packaging or container checks before merging to main."
+          },
+          "python": {
+            "exampleConfigFiles": [
+              ".github/workflows/*",
+              "azure-pipelines.yml"
+            ],
+            "exampleTools": [],
+            "notes": "Ensure CI runs linting, type checking (if used), tests, and packaging or container checks for Python services before merging.",
+            "verification": "Open the CI configuration and verify there is a job or stage that runs linting, type checking (if used), tests, and any packaging or container checks before merging to main."
+          },
+          "typescript-js": {
+            "exampleConfigFiles": [
+              ".github/workflows/*",
+              "azure-pipelines.yml"
+            ],
+            "exampleTools": [],
+            "notes": "Expose a single npm script (e.g., `npm run ci`) that mirrors the CI pipeline so contributors can reproduce failures locally.",
+            "verification": "Open the CI configuration and verify there is a job or stage that runs linting, type checking, tests, build, and any required container checks before merging to main."
+          }
+        }
+      },
+      {
+        "appliesTo": {
+          "stacks": [
+            "typescript-js",
+            "csharp-dotnet",
+            "python"
+          ]
+        },
+        "ciHints": {
+          "azure-devops": {
+            "stage": "quality"
+          },
+          "github-actions": {
+            "job": "ci"
+          }
+        },
+        "description": "Automatic code formatting to maintain a consistent style across all contributors.",
+        "id": "code-formatter",
+        "label": "Code Formatter",
+        "stackHints": {
+          "csharp-dotnet": {
+            "exampleConfigFiles": [
+              ".editorconfig"
+            ],
+            "exampleTools": [
+              "dotnet format"
+            ],
+            "notes": "Use .editorconfig and dotnet-format to keep C# style consistent across contributors.",
+            "verification": "Run the configured formatter or code style enforcement (for example, `dotnet format`) and confirm that code in the repository conforms to the defined rules."
+          },
+          "python": {
+            "exampleConfigFiles": [
+              "pyproject.toml"
+            ],
+            "exampleTools": [
+              "black"
+            ],
+            "notes": "Use black (or an equivalent opinionated formatter) and treat its output as the single source of truth for code style.",
+            "verification": "Run the configured formatter (for example, `black .` or `black --check .`) and confirm it reports clean formatting on committed code and auto-fixes as expected locally."
+          },
+          "typescript-js": {
+            "exampleConfigFiles": [
+              ".prettierrc.*",
+              ".prettierignore"
+            ],
+            "exampleTools": [
+              "prettier"
+            ],
+            "notes": "Run Prettier in check mode in CI; auto-fix locally via pre-commit hooks or editor integration.",
+            "verification": "Run the formatter in check mode (for example, `npm run format:check`) and confirm it reports clean formatting on committed code and auto-fixes as expected locally."
+          }
+        }
+      },
+      {
+        "appliesTo": {
+          "stacks": [
+            "typescript-js",
+            "csharp-dotnet",
+            "python"
+          ]
+        },
+        "ciHints": {
+          "azure-devops": {
+            "stage": "quality"
+          },
+          "github-actions": {
+            "job": "ci"
+          }
+        },
+        "description": "Use git hooks to run linting, formatting, tests, and commit linting before changes are committed.",
+        "id": "pre-commit-hooks",
+        "label": "Pre-Commit Hooks",
+        "stackHints": {
+          "csharp-dotnet": {
+            "exampleConfigFiles": [
+              "lefthook.yml"
+            ],
+            "exampleTools": [
+              "Lefthook"
+            ],
+            "notes": "Configure Lefthook or similar to run formatting and basic checks on staged files before commits.",
+            "verification": "Inspect the hook configuration (for example, Lefthook or similar) and confirm it runs at least formatting and basic checks on staged changes before commits or pushes."
+          },
+          "python": {
+            "exampleConfigFiles": [
+              ".pre-commit-config.yaml"
+            ],
+            "exampleTools": [
+              "pre-commit"
+            ],
+            "notes": "Use pre-commit to run ruff, black, and optionally mypy on staged files before committing.",
+            "verification": "Inspect .pre-commit-config.yaml and confirm that hooks for linting, formatting, and optionally type checking are enabled and run on changed files before commits."
+          },
+          "typescript-js": {
+            "exampleConfigFiles": [
+              ".husky/",
+              "package.json"
+            ],
+            "exampleTools": [
+              "husky",
+              "lint-staged"
+            ],
+            "notes": "Run ESLint and Prettier on staged files and enforce commit message format via commit-msg hooks.",
+            "verification": "Inspect the pre-commit and commit-msg hooks (for example, files under .husky or other hook tooling) and confirm they run linting/formatting and commit linting on staged changes."
+          }
+        }
+      },
+      {
+        "appliesTo": {
+          "stacks": [
+            "typescript-js",
+            "csharp-dotnet",
+            "python"
+          ]
+        },
+        "ciHints": {
+          "azure-devops": {
+            "stage": "quality"
+          },
+          "github-actions": {
+            "job": "ci"
+          }
+        },
+        "description": "Use static type checking to catch errors before runtime and enforce strictness on new code.",
+        "id": "type-checking",
+        "label": "Type Checking",
+        "stackHints": {
+          "csharp-dotnet": {
+            "exampleConfigFiles": [
+              ".editorconfig",
+              "Directory.Build.props",
+              "*.csproj"
+            ],
+            "exampleTools": [
+              "Roslyn analyzers"
+            ],
+            "notes": "Enable nullable reference types and relevant analyzers to catch type and nullability issues at compile time. C# project files (*.csproj) indicate the presence of projects that can be type-checked.",
+            "optionalFiles": [
+              "Directory.Build.props"
+            ],
+            "requiredFiles": [
+              ".editorconfig"
+            ],
+            "requiredScripts": [
+              "typecheck"
+            ],
+            "verification": ".editorconfig must exist; Directory.Build.props is optional for shared build configuration."
+          },
+          "python": {
+            "exampleConfigFiles": [
+              "mypy.ini",
+              "pyproject.toml"
+            ],
+            "exampleTools": [
+              "mypy"
+            ],
+            "notes": "Adopt gradual typing with type hints and mypy, focusing first on critical modules and new code paths.",
+            "optionalFiles": [
+              "mypy.ini"
+            ],
+            "requiredFiles": [
+              "pyproject.toml"
+            ],
+            "requiredScripts": [
+              "typecheck"
+            ],
+            "verification": "pyproject.toml (or mypy.ini) signals that mypy configuration is available for the repository."
+          },
+          "typescript-js": {
+            "exampleConfigFiles": [
+              "tsconfig.json"
+            ],
+            "exampleTools": [
+              "TypeScript compiler (tsc)"
+            ],
+            "notes": "Enable strict mode ('strict': true) and treat type-check failures as CI failures for new code; gradually expand strictness into legacy modules.",
+            "requiredFiles": [
+              "tsconfig.json"
+            ],
+            "requiredScripts": [
+              "typecheck"
+            ],
+            "verification": "Presence of tsconfig.json indicates type-checking is configured for the repository."
+          }
+        }
+      },
+      {
+        "appliesTo": {
+          "stacks": [
+            "typescript-js",
+            "csharp-dotnet",
+            "python"
+          ]
+        },
+        "ciHints": {
+          "azure-devops": {
+            "stage": "quality"
+          },
+          "github-actions": {
+            "job": "ci"
+          }
+        },
+        "description": "Lock dependencies and scan regularly for known vulnerabilities; fail CI on newly introduced high-severity issues.",
+        "id": "dependency-security",
+        "label": "Dependency Management & Vulnerability Scanning",
+        "stackHints": {
+          "csharp-dotnet": {
+            "exampleConfigFiles": [
+              "packages.lock.json",
+              "*.csproj"
+            ],
+            "exampleTools": [
+              "dotnet list package --vulnerable"
+            ],
+            "notes": "Enable package lock files and use vulnerability scanning to track and remediate high-risk dependencies.",
+            "optionalFiles": [
+              "packages.lock.json"
+            ],
+            "verification": "Dependency lockfile or package reference is present; security scanning is configured."
+          },
+          "python": {
+            "exampleConfigFiles": [
+              "requirements.txt",
+              "Pipfile.lock",
+              "poetry.lock"
+            ],
+            "exampleTools": [
+              "pip-audit",
+              "safety"
+            ],
+            "notes": "Pin dependency versions and routinely scan for vulnerabilities, prioritizing fixes for critical and high-severity issues.",
+            "optionalFiles": [
+              "requirements.txt",
+              "Pipfile.lock",
+              "poetry.lock"
+            ],
+            "verification": "Dependency lockfile is present; security scanning is configured in CI or project tooling."
+          },
+          "typescript-js": {
+            "exampleConfigFiles": [
+              "package-lock.json",
+              "pnpm-lock.yaml",
+              "yarn.lock"
+            ],
+            "exampleTools": [
+              "npm audit",
+              "Snyk"
+            ],
+            "notes": "Require a lockfile for reproducible installs and pin Node.js/tooling versions; block merges on new high-severity vulnerabilities.",
+            "optionalFiles": [
+              "package-lock.json",
+              "pnpm-lock.yaml",
+              "yarn.lock"
+            ],
+            "verification": "Dependency lockfile is present; security scanning is configured in CI or project tooling."
+          }
+        }
+      },
+      {
+        "appliesTo": {
+          "stacks": [
+            "typescript-js",
+            "csharp-dotnet",
+            "python"
+          ]
+        },
+        "ciHints": {
+          "azure-devops": {
+            "stage": "quality"
+          },
+          "github-actions": {
+            "job": "ci"
+          }
+        },
+        "description": "Specify required runtime/engine versions in package manifests to ensure environment stability and prevent version-related issues across development teams.",
+        "id": "runtime-version",
+        "label": "Runtime Version Specification",
+        "stackHints": {
+          "csharp-dotnet": {
+            "exampleConfigFiles": [
+              "*.csproj",
+              "global.json"
+            ],
+            "exampleTools": [],
+            "notes": "Specify TargetFramework in .csproj files (e.g., <TargetFramework>net8.0</TargetFramework>) and optionally use global.json to pin the SDK version (e.g., { \"sdk\": { \"version\": \"8.0.100\" } }) for consistent builds across the team.",
+            "optionalFiles": [
+              "global.json"
+            ],
+            "verification": ".csproj files must specify TargetFramework; global.json is recommended to pin SDK version."
+          },
+          "python": {
+            "exampleConfigFiles": [
+              "pyproject.toml",
+              "setup.py",
+              ".python-version"
+            ],
+            "exampleTools": [],
+            "notes": "Specify python_requires in pyproject.toml (e.g., requires-python = \">=3.9\") or setup.py (e.g., python_requires='>=3.9'). Consider adding .python-version for pyenv users to automatically switch to the correct Python version.",
+            "optionalFiles": [
+              ".python-version"
+            ],
+            "requiredFiles": [
+              "pyproject.toml"
+            ],
+            "verification": "pyproject.toml or setup.py must specify python_requires; .python-version is recommended for local development."
+          },
+          "typescript-js": {
+            "exampleConfigFiles": [
+              "package.json"
+            ],
+            "exampleTools": [],
+            "notes": "Specify the 'engines' field in package.json to define the required Node.js version (e.g., \"engines\": { \"node\": \">=18.0.0\" }). This helps prevent environment-related bugs and ensures all developers use compatible Node.js versions.",
+            "requiredFiles": [
+              "package.json"
+            ],
+            "verification": "package.json must contain an 'engines' field specifying the required Node.js version."
+          }
+        }
+      },
+      {
+        "appliesTo": {
+          "stacks": [
+            "typescript-js",
+            "csharp-dotnet",
+            "python"
+          ]
+        },
+        "ciHints": {
+          "azure-devops": {
+            "stage": "docs"
+          },
+          "github-actions": {
+            "job": "ci"
+          }
+        },
+        "description": "Maintain a comprehensive README and, where applicable, auto-generated API docs to support onboarding and maintainability.",
+        "id": "documentation",
+        "label": "Documentation Standards",
+        "stackHints": {
+          "csharp-dotnet": {
+            "exampleConfigFiles": [
+              "README.md",
+              "docfx.json"
+            ],
+            "exampleTools": [
+              "DocFX"
+            ],
+            "notes": "Keep README and API docs in sync with the solution structure and public surface area.",
+            "optionalFiles": [
+              "docs/",
+              "docfx.json"
+            ],
+            "requiredFiles": [
+              "README.md"
+            ],
+            "verification": "README.md is present in the repository root; docs/ directory or DocFX configuration exists if applicable."
+          },
+          "python": {
+            "exampleConfigFiles": [
+              "README.md",
+              "docs/"
+            ],
+            "exampleTools": [
+              "Sphinx",
+              "MkDocs"
+            ],
+            "notes": "Ensure README explains environment setup and core commands, and generate API docs from docstrings where appropriate.",
+            "optionalFiles": [
+              "docs/",
+              "mkdocs.yml"
+            ],
+            "requiredFiles": [
+              "README.md"
+            ],
+            "verification": "README.md is present in the repository root; docs/ directory or documentation tooling configuration exists if applicable."
+          },
+          "typescript-js": {
+            "exampleConfigFiles": [
+              "README.md",
+              "docs/"
+            ],
+            "exampleTools": [
+              "JSDoc",
+              "TypeDoc"
+            ],
+            "notes": "README should describe setup, scripts, and architecture; generate API docs from TypeScript types and JSDoc where helpful.",
+            "optionalFiles": [
+              "docs/",
+              "typedoc.json"
+            ],
+            "requiredFiles": [
+              "README.md"
+            ],
+            "verification": "README.md is present in the repository root; docs/ directory or documentation tooling configuration exists if applicable."
+          }
+        }
+      },
+      {
+        "appliesTo": {
+          "stacks": [
+            "typescript-js",
+            "csharp-dotnet",
+            "python"
+          ]
+        },
+        "ciHints": {
+          "azure-devops": {
+            "stage": "governance"
+          },
+          "github-actions": {
+            "job": "ci"
+          }
+        },
+        "description": "Include standard governance files (LICENSE, CODE_OF_CONDUCT.md, CONTRIBUTING.md), branch protection rules, and review standards to define legal, ethical, and workflow expectations.",
+        "id": "repository-governance",
+        "label": "Repository Governance",
+        "stackHints": {
+          "csharp-dotnet": {
+            "exampleConfigFiles": [
+              "LICENSE",
+              "CODE_OF_CONDUCT.md",
+              "CONTRIBUTING.md"
+            ],
+            "exampleTools": [],
+            "notes": "Document contribution expectations and ensure legal and code-of-conduct policies are easy to find.",
+            "optionalFiles": [
+              "CODE_OF_CONDUCT.md",
+              "CONTRIBUTING.md"
+            ],
+            "requiredFiles": [
+              "LICENSE"
+            ],
+            "verification": "LICENSE file is present in the repository root; CODE_OF_CONDUCT.md and CONTRIBUTING.md are present for contribution guidance."
+          },
+          "python": {
+            "exampleConfigFiles": [
+              "LICENSE",
+              "CODE_OF_CONDUCT.md",
+              "CONTRIBUTING.md"
+            ],
+            "exampleTools": [],
+            "notes": "Spell out contributor responsibilities for tests, documentation, and review so expectations are clear for Python-focused teams.",
+            "optionalFiles": [
+              "CODE_OF_CONDUCT.md",
+              "CONTRIBUTING.md"
+            ],
+            "requiredFiles": [
+              "LICENSE"
+            ],
+            "verification": "LICENSE file is present in the repository root; CODE_OF_CONDUCT.md and CONTRIBUTING.md are present for contribution guidance."
+          },
+          "typescript-js": {
+            "exampleConfigFiles": [
+              "LICENSE",
+              "CODE_OF_CONDUCT.md",
+              "CONTRIBUTING.md"
+            ],
+            "exampleTools": [],
+            "notes": "Use an SPDX license identifier in package.json and describe review expectations, tests, and docs requirements in CONTRIBUTING.md.",
+            "optionalFiles": [
+              "CODE_OF_CONDUCT.md",
+              "CONTRIBUTING.md"
+            ],
+            "requiredFiles": [
+              "LICENSE"
+            ],
+            "verification": "LICENSE file is present in the repository root; CODE_OF_CONDUCT.md and CONTRIBUTING.md are present for contribution guidance."
+          }
+        }
+      }
+    ],
+    "optionalEnhancements": [
+      {
+        "appliesTo": {
+          "stacks": [
+            "typescript-js",
+            "csharp-dotnet",
+            "python"
+          ]
+        },
+        "ciHints": {
+          "azure-devops": {
+            "stage": "observability"
+          },
+          "github-actions": {
+            "job": "ci"
+          }
+        },
+        "description": "Standardize error handling and structured logging to make debugging and production monitoring easier.",
+        "id": "observability",
+        "label": "Observability (Logging & Error Handling)",
+        "stackHints": {
+          "csharp-dotnet": {
+            "exampleConfigFiles": [
+              "appsettings.json"
+            ],
+            "exampleTools": [
+              "Serilog",
+              "NLog"
+            ],
+            "notes": "Configure structured logging for your .NET services and ensure exceptions and key events are logged with useful context.",
+            "verification": "Confirm that a structured logging library (such as Serilog or NLog) is configured with an agreed sink and format, and that the application logs meaningful context for errors and key events."
+          },
+          "python": {
+            "exampleConfigFiles": [
+              "logging configuration files",
+              "pyproject.toml"
+            ],
+            "exampleTools": [
+              "structlog",
+              "loguru"
+            ],
+            "notes": "Use structured logging for Python services and ensure critical paths record enough context to debug issues after the fact.",
+            "verification": "Confirm that a structured logging setup (such as structlog or configured logging with JSON formatting) is in place and that critical paths log enough information to debug failures in production."
+          },
+          "typescript-js": {
+            "exampleConfigFiles": [],
+            "exampleTools": [
+              "Winston",
+              "Pino"
+            ],
+            "notes": "Adopt structured JSON logging with correlation IDs and send logs to a centralized sink in production.",
+            "verification": "Confirm that a structured logging library (such as Winston or Pino) is configured to emit JSON or key-value logs and that error handling routes important failures through this logger."
+          }
+        }
+      }
+    ],
+    "recommended": [
+      {
+        "appliesTo": {
+          "stacks": [
+            "typescript-js",
+            "csharp-dotnet",
+            "python"
+          ]
+        },
+        "ciHints": {
+          "azure-devops": {
+            "stage": "test"
+          },
+          "github-actions": {
+            "job": "ci"
+          }
+        },
+        "description": "Test how components interact with each other and external systems, running after unit tests with more relaxed coverage thresholds.",
+        "id": "integration-testing",
+        "label": "Integration Testing",
+        "stackHints": {
+          "csharp-dotnet": {
+            "exampleConfigFiles": [
+              "*.IntegrationTests.csproj"
+            ],
+            "exampleTools": [
+              "xUnit",
+              "NUnit",
+              "MSTest"
+            ],
+            "notes": "Create dedicated integration test projects that exercise real infrastructure or service boundaries where appropriate.",
+            "verification": "Confirm there is a test project or configuration dedicated to integration or API tests and run it to verify external or cross-service interactions behave as expected."
+          },
+          "python": {
+            "exampleConfigFiles": [
+              "tests/integration/"
+            ],
+            "exampleTools": [
+              "pytest"
+            ],
+            "notes": "Separate integration tests from unit tests, using fixtures to handle databases, services, or other external systems.",
+            "verification": "Confirm there is a separate integration or API test suite (for example, a dedicated tests/integration directory) and run it to verify interactions with databases, services, or external systems."
+          },
+          "typescript-js": {
+            "exampleConfigFiles": [
+              "jest.config.*",
+              "playwright.config.*"
+            ],
+            "exampleTools": [
+              "Jest",
+              "Supertest",
+              "Playwright"
+            ],
+            "notes": "Use Supertest for HTTP APIs and Playwright or similar tools for end-to-end flows; keep integration suites slower but reliable.",
+            "verification": "Confirm there is a separate integration or end-to-end test command or configuration and run it to verify that cross-component flows behave as expected."
+          }
+        }
+      },
+      {
+        "appliesTo": {
+          "stacks": [
+            "typescript-js",
+            "csharp-dotnet",
+            "python"
+          ]
+        },
+        "ciHints": {
+          "azure-devops": {
+            "stage": "performance"
+          },
+          "github-actions": {
+            "job": "performance"
+          }
+        },
+        "description": "Establish performance baselines and monitor for regressions using lightweight benchmarks or audits in CI.",
+        "id": "performance-baselining",
+        "label": "Performance Baselines",
+        "stackHints": {
+          "csharp-dotnet": {
+            "exampleConfigFiles": [
+              "*.csproj"
+            ],
+            "exampleTools": [
+              "BenchmarkDotNet"
+            ],
+            "notes": "Use BenchmarkDotNet or similar to track performance of critical methods or endpoints over time.",
+            "verification": "Identify and run the configured performance or benchmarking suite (for example, BenchmarkDotNet) and review the output to ensure it is tracked against historical or target values."
+          },
+          "python": {
+            "exampleConfigFiles": [
+              "pytest.ini",
+              "pyproject.toml"
+            ],
+            "exampleTools": [
+              "pytest-benchmark",
+              "cProfile"
+            ],
+            "notes": "Use simple benchmarks or profiling runs to characterize bottlenecks and watch for regressions in critical workflows.",
+            "verification": "Identify and run the configured performance checks or benchmarks (for example, pytest-benchmark or cProfile-based scripts) and confirm that their results are recorded and compared over time."
+          },
+          "typescript-js": {
+            "exampleConfigFiles": [
+              "lighthouserc.json"
+            ],
+            "exampleTools": [
+              "Lighthouse CI",
+              "custom Node.js benchmarks"
+            ],
+            "notes": "Run Lighthouse CI for web apps and basic Node benchmarks on critical endpoints; schedule runs or limit to key branches to keep CI fast.",
+            "verification": "Identify and run the configured performance or Lighthouse-style checks and verify that key metrics are captured and compared to documented baselines."
+          }
+        }
+      },
+      {
+        "appliesTo": {
+          "stacks": [
+            "typescript-js",
+            "csharp-dotnet",
+            "python"
+          ]
+        },
+        "ciHints": {
+          "azure-devops": {
+            "stage": "quality"
+          },
+          "github-actions": {
+            "job": "ci"
+          }
+        },
+        "description": "Measure cyclomatic complexity or similar metrics to keep code maintainable, starting as a warning-only check.",
+        "id": "complexity-analysis",
+        "label": "Complexity Analysis",
+        "stackHints": {
+          "csharp-dotnet": {
+            "exampleConfigFiles": [
+              "sonar-project.properties"
+            ],
+            "exampleTools": [
+              "SonarQube",
+              "Visual Studio code metrics"
+            ],
+            "notes": "Use code metrics or Sonar analysis to flag overly complex methods and refactor them over time.",
+            "verification": "Run the configured code metrics or Sonar analysis and review complexity reports for key modules, ensuring that new or changed code stays within acceptable limits."
+          },
+          "python": {
+            "exampleConfigFiles": [
+              "radon.cfg"
+            ],
+            "exampleTools": [
+              "radon"
+            ],
+            "notes": "Use radon or similar tools to track complexity of Python functions and keep new code within acceptable limits.",
+            "verification": "Run the configured complexity tool (for example, radon) on the codebase and review the report to ensure new or heavily changed functions are not excessively complex."
+          },
+          "typescript-js": {
+            "exampleConfigFiles": [
+              ".eslintrc.*",
+              "sonar-project.properties"
+            ],
+            "exampleTools": [
+              "ESLint complexity rules",
+              "SonarQube"
+            ],
+            "notes": "Warn on overly complex functions and methods; fail CI only when new or modified code exceeds thresholds.",
+            "verification": "Run the configured complexity tooling or rules (for example, ESLint complexity rules or Sonar analysis) and review any hot spots, ensuring new code does not exceed agreed thresholds."
+          }
+        }
+      },
+      {
+        "appliesTo": {
+          "stacks": [
+            "typescript-js",
+            "csharp-dotnet",
+            "python"
+          ]
+        },
+        "ciHints": {
+          "azure-devops": {
+            "stage": "quality"
+          },
+          "github-actions": {
+            "job": "ci"
+          }
+        },
+        "description": "Run accessibility checks on web-facing components to detect critical issues and improve inclusive UX.",
+        "id": "accessibility-auditing",
+        "label": "Accessibility Auditing",
+        "stackHints": {
+          "csharp-dotnet": {
+            "exampleConfigFiles": [],
+            "exampleTools": [
+              "axe-core",
+              "Accessibility Insights"
+            ],
+            "notes": "Apply accessibility tooling to ASP.NET or Blazor front-ends and review issues alongside functional testing.",
+            "verification": "For web-facing apps, run the configured accessibility checks or tools against your main UI endpoints and confirm that blocking accessibility issues are addressed."
+          },
+          "python": {
+            "exampleConfigFiles": [],
+            "exampleTools": [
+              "pa11y"
+            ],
+            "notes": "Use headless browser-based tools to scan Python-backed web UIs for accessibility issues on high-traffic routes.",
+            "verification": "For Python-backed web UIs, run the configured accessibility tooling (for example, pa11y or axe via a headless browser) against key routes and verify that critical issues are fixed or tracked."
+          },
+          "typescript-js": {
+            "exampleConfigFiles": [],
+            "exampleTools": [
+              "axe-core",
+              "Lighthouse accessibility audits"
+            ],
+            "notes": "Run accessibility checks against key pages or components in CI; fail on critical violations while treating minor issues as warnings initially.",
+            "verification": "For web-facing apps, run the configured accessibility tooling (for example, axe, pa11y, or Lighthouse accessibility audits) against key pages and confirm that critical issues are resolved."
+          }
+        }
+      }
+    ]
+  },
+  "ciSystems": [
+    "azure-devops",
+    "github-actions"
+  ],
+  "meta": {
+    "complexityChecks": {
+      "description": "When supported by the stack, run cyclomatic complexity or similar metrics in CI as a warning-only check initially.",
+      "enabledByDefault": true
+    },
+    "defaultCoverageThreshold": 0.8,
+    "migrationGuide": [
+      {
+        "description": "Start by adding pre-commit hooks and core formatting/linting so developers get fast feedback without touching CI.",
+        "focusIds": [
+          "pre-commit-hooks",
+          "linting",
+          "code-formatter"
+        ],
+        "notes": "Keep hooks fast and focused on changed files to avoid slowing down day-to-day work.",
+        "step": 1,
+        "title": "Establish Local Safety Nets First"
+      },
+      {
+        "description": "Introduce CI quality gates that mirror local checks, but treat existing violations as warnings wherever possible.",
+        "focusIds": [
+          "ci-quality-gates",
+          "linting",
+          "code-formatter",
+          "commit-linting"
+        ],
+        "notes": "Use diff-based tools or baselines so only new violations break builds; legacy issues remain visible but non-blocking.",
+        "step": 2,
+        "title": "Mirror Local Checks in CI (Soft-Fail on Legacy)"
+      },
+      {
+        "description": "Enable type-checking, coverage thresholds, and dependency/vulnerability scanning with gradual enforcement.",
+        "focusIds": [
+          "type-checking",
+          "unit-test-runner",
+          "unit-test-reporter",
+          "dependency-security"
+        ],
+        "notes": "Pin tool and runtime versions in CI and containers to avoid flaky differences across environments.",
+        "step": 3,
+        "title": "Add Type Safety, Coverage, and Dependency Security"
+      },
+      {
+        "description": "Add documentation standards, governance files, integration testing, performance baselines, complexity analysis, accessibility auditing, and (optionally) ML-specific practices for data-heavy Python repos.",
+        "focusIds": [
+          "documentation",
+          "repository-governance",
+          "integration-testing",
+          "performance-baselining",
+          "complexity-analysis",
+          "accessibility-auditing"
+        ],
+        "notes": "Tackle recommended items in order of business value; backend-only repos can skip web-focused checks like accessibility. For AI/ML-heavy Python teams, consider extending containerization with data versioning (DVC) and unit tests with data quality checks (e.g., Great Expectations) as part of this step.",
+        "step": 4,
+        "title": "Layer in Docs, Governance, and Recommended Checks"
+      }
+    ],
+    "qualityGatePolicy": {
+      "description": "New quality checks should warn on existing code and fail CI only for violations introduced in new or changed code, to reduce friction on legacy codebases.",
+      "preferSoftFailOnLegacy": true
+    }
+  },
+  "stacks": {
+    "csharp-dotnet": {
+      "label": "C# / .NET",
+      "languageFamily": "dotnet"
+    },
+    "python": {
+      "label": "Python",
+      "languageFamily": "python"
+    },
+    "typescript-js": {
+      "label": "TypeScript / JavaScript",
+      "languageFamily": "js"
+    }
+  },
+  "version": 1
+}