@oddessentials/repo-standards 4.4.0 → 5.1.0

package/dist/config/standards.json

@@ -1,6 +1,244 @@
 {
   "checklist": {
     "core": [
+      {
+        "appliesTo": {
+          "stacks": [
+            "typescript-js",
+            "csharp-dotnet",
+            "python",
+            "rust",
+            "go"
+          ]
+        },
+        "ciHints": {
+          "azure-devops": {
+            "notes": "Run CRLF detection early in pipeline before other checks.",
+            "stage": "quality"
+          },
+          "github-actions": {
+            "job": "ci",
+            "notes": "Add .gitattributes check as first step in CI job."
+          }
+        },
+        "description": "Enforce line endings at the Git layer using .gitattributes. Mark text files with appropriate EOL handling (eol=lf for shell scripts, eol=auto for most files) and binary files as binary to prevent corruption. This prevents 'works locally, fails in CI' issues caused by CRLF/LF mismatches.",
+        "enforcement": "required",
+        "executionStage": "pre-commit",
+        "id": "gitattributes-eol",
+        "label": "Git Attributes (Line Endings)",
+        "severity": "error",
+        "stackHints": {
+          "csharp-dotnet": {
+            "exampleConfigFiles": [
+              ".gitattributes",
+              ".editorconfig"
+            ],
+            "exampleTools": [
+              "git"
+            ],
+            "machineCheck": {
+              "command": "git ls-files --eol | grep -E 'w/crlf.*\\.sh$' && exit 1 || exit 0",
+              "description": "Verify no CRLF in shell scripts",
+              "expectExitCode": 0
+            },
+            "notes": "Use .gitattributes for EOL authority. Mark *.sh, *.ps1 scripts appropriately. .editorconfig drives editor behavior but .gitattributes is the source of truth for Git operations.",
+            "optionalFiles": [
+              ".editorconfig"
+            ],
+            "requiredFiles": [
+              ".gitattributes"
+            ],
+            "verification": "Run 'git ls-files --eol' to check EOL consistency."
+          },
+          "go": {
+            "exampleConfigFiles": [
+              ".gitattributes",
+              ".editorconfig"
+            ],
+            "exampleTools": [
+              "git"
+            ],
+            "machineCheck": {
+              "command": "git ls-files --eol | grep -E 'w/crlf.*\\.sh$' && exit 1 || exit 0",
+              "description": "Verify no CRLF in shell scripts",
+              "expectExitCode": 0
+            },
+            "notes": "Go files should use LF for consistency. Mark *.go as text. Shell scripts (*.sh) must use eol=lf. Binary artifacts should be marked as binary.",
+            "optionalFiles": [
+              ".editorconfig"
+            ],
+            "requiredFiles": [
+              ".gitattributes"
+            ],
+            "verification": "Run 'git ls-files --eol' to verify EOL handling."
+          },
+          "python": {
+            "exampleConfigFiles": [
+              ".gitattributes",
+              ".editorconfig"
+            ],
+            "exampleTools": [
+              "git"
+            ],
+            "machineCheck": {
+              "command": "git ls-files --eol | grep -E 'w/crlf.*\\.py$' && exit 1 || exit 0",
+              "description": "Verify no CRLF in Python files",
+              "expectExitCode": 0
+            },
+            "notes": "Python files should use LF endings for cross-platform compatibility. Mark *.py as eol=lf in .gitattributes. Shebang scripts fail with CRLF.",
+            "optionalFiles": [
+              ".editorconfig"
+            ],
+            "requiredFiles": [
+              ".gitattributes"
+            ],
+            "verification": "Run 'git ls-files --eol' and verify Python files use LF."
+          },
+          "rust": {
+            "exampleConfigFiles": [
+              ".gitattributes",
+              ".editorconfig"
+            ],
+            "exampleTools": [
+              "git"
+            ],
+            "machineCheck": {
+              "command": "git ls-files --eol | grep -E 'w/crlf.*\\.sh$' && exit 1 || exit 0",
+              "description": "Verify no CRLF in shell scripts",
+              "expectExitCode": 0
+            },
+            "notes": "Mark *.rs, *.toml as text with auto EOL handling. Mark shell scripts as eol=lf. Binary files (*.exe, *.dll) should be marked as binary.",
+            "optionalFiles": [
+              ".editorconfig"
+            ],
+            "requiredFiles": [
+              ".gitattributes"
+            ],
+            "verification": "Run 'git ls-files --eol' to verify EOL consistency."
+          },
+          "typescript-js": {
+            "exampleConfigFiles": [
+              ".gitattributes",
+              ".editorconfig"
+            ],
+            "exampleTools": [
+              "git"
+            ],
+            "machineCheck": {
+              "command": "git ls-files --eol | grep -E 'w/crlf.*\\.(sh|bash|py)$' && exit 1 || exit 0",
+              "description": "Verify no CRLF in shell/script files",
+              "expectExitCode": 0
+            },
+            "notes": "Use .gitattributes as the authority for EOL; .editorconfig is supplementary for editor display. Mark *.sh, *.bash as eol=lf. After adding .gitattributes, run 'git add --renormalize .' to fix existing files. Windows contributors should set core.autocrlf=false.",
+            "optionalFiles": [
+              ".editorconfig"
+            ],
+            "requiredFiles": [
+              ".gitattributes"
+            ],
+            "verification": "Run 'git ls-files --eol' and verify no unexpected CRLF in LF-only files."
+          }
+        }
+      },
+      {
+        "appliesTo": {
+          "stacks": [
+            "typescript-js",
+            "csharp-dotnet",
+            "python",
+            "rust",
+            "go"
+          ]
+        },
+        "ciHints": {
+          "azure-devops": {
+            "notes": "Run CRLF detection as the first quality check before linting or testing.",
+            "stage": "quality"
+          },
+          "github-actions": {
+            "job": "ci",
+            "notes": "Add CRLF detection step before main CI steps."
+          }
+        },
+        "description": "Fail CI early for Linux-executed files containing CRLF line endings. Shell scripts, Python files, and other interpreted files fail silently or with cryptic errors when they contain \\r characters. Detect this before running deeper CI steps.",
+        "enforcement": "required",
+        "executionStage": "ci-pr",
+        "id": "crlf-detection",
+        "label": "CRLF Detection in CI",
+        "severity": "error",
+        "stackHints": {
+          "csharp-dotnet": {
+            "exampleConfigFiles": [],
+            "exampleTools": [
+              "file",
+              "grep"
+            ],
+            "machineCheck": {
+              "command": "git ls-files --eol | grep -E 'w/crlf.*\\.sh$' && exit 1 || exit 0",
+              "description": "Detect CRLF in shell scripts",
+              "expectExitCode": 0
+            },
+            "notes": "Detect CRLF in shell scripts and CI configuration files. C# source files can tolerate CRLF but shell scripts cannot.",
+            "verification": "Run CRLF detection on .sh files in CI."
+          },
+          "go": {
+            "exampleConfigFiles": [],
+            "exampleTools": [
+              "file",
+              "grep"
+            ],
+            "machineCheck": {
+              "command": "git ls-files --eol | grep -E 'w/crlf.*\\.(sh|bash)$' && exit 1 || exit 0",
+              "description": "Detect CRLF in shell scripts",
+              "expectExitCode": 0
+            },
+            "notes": "Go source files tolerate CRLF but shell scripts and Makefiles do not. Check .sh, Makefile, and go.mod for CRLF.",
+            "verification": "Run CRLF detection on shell scripts and Makefiles."
+          },
+          "python": {
+            "exampleConfigFiles": [],
+            "exampleTools": [
+              "file",
+              "grep"
+            ],
+            "machineCheck": {
+              "command": "git ls-files --eol | grep -E 'w/crlf.*\\.(py|sh)$' && exit 1 || exit 0",
+              "description": "Detect CRLF in Python/shell files",
+              "expectExitCode": 0
+            },
+            "notes": "Python shebang scripts fail with CRLF. Check all .py and .sh files for CRLF before running pytest or other Python tools.",
+            "verification": "Run CRLF detection on Python and shell files."
+          },
+          "rust": {
+            "exampleConfigFiles": [],
+            "exampleTools": [
+              "file",
+              "grep"
+            ],
+            "machineCheck": {
+              "command": "git ls-files --eol | grep -E 'w/crlf.*\\.(sh|bash)$' && exit 1 || exit 0",
+              "description": "Detect CRLF in shell scripts",
+              "expectExitCode": 0
+            },
+            "notes": "Rust build scripts (build.rs) and shell scripts must not have CRLF. Cargo tolerates CRLF in .rs files but shell invocations fail.",
+            "verification": "Run CRLF detection on shell and build scripts."
+          },
+          "typescript-js": {
+            "exampleConfigFiles": [],
+            "exampleTools": [
+              "file",
+              "grep"
+            ],
+            "machineCheck": {
+              "command": "git ls-files --eol | grep -E 'w/crlf.*\\.(sh|js|ts|mjs|cjs)$' && exit 1 || exit 0",
+              "description": "Detect CRLF in script files",
+              "expectExitCode": 0
+            },
+            "notes": "Check for CRLF in .sh, .js, .ts, .json files early in CI. Use 'file' command or grep for \\r to detect issues before they cause cryptic failures.",
+            "verification": "Run 'git ls-files --eol | grep w/crlf' and verify no unexpected CRLF files."
+          }
+        }
+      },
       {
         "appliesTo": {
           "stacks": [
@@ -21,6 +259,7 @@
         },
         "description": "Maintain proper .gitignore and .dockerignore files to prevent committing secrets, build artifacts, or unnecessary files.",
         "enforcement": "required",
+        "executionStage": "pre-commit",
         "id": "gitignore-and-dockerignore",
         "label": "Git and Docker Ignore Files",
         "severity": "error",
@@ -117,8 +356,10 @@
         },
         "description": "Run static code linting to enforce consistency and catch common issues early.",
         "enforcement": "required",
+        "executionStage": "pre-commit",
         "id": "linting",
         "label": "Linting",
+        "scopeToChangedFiles": true,
         "severity": "error",
         "stackHints": {
           "csharp-dotnet": {
@@ -284,6 +525,7 @@
         },
         "description": "Provide a deterministic unit test framework with a single command to run all tests.",
         "enforcement": "required",
+        "executionStage": "pre-push",
         "id": "unit-test-runner",
         "label": "Unit Test Runner",
         "severity": "error",
@@ -420,6 +662,7 @@
         },
         "description": "Provide a Dockerfile and, if applicable, a docker-compose file for local dev and CI parity.",
         "enforcement": "required",
+        "executionStage": "ci-pr",
         "id": "containerization",
         "label": "Containerization (Docker / Docker Compose)",
         "severity": "error",
@@ -521,6 +764,7 @@
         },
         "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.",
         "enforcement": "required",
+        "executionStage": "release",
         "id": "semantic-versioning",
         "label": "Semantic Versioning",
         "severity": "error",
@@ -637,6 +881,126 @@
           }
         }
       },
+      {
+        "appliesTo": {
+          "stacks": [
+            "typescript-js",
+            "csharp-dotnet",
+            "python",
+            "rust",
+            "go"
+          ]
+        },
+        "ciHints": {
+          "azure-devops": {
+            "notes": "Run the version guard in PR validation jobs before merge.",
+            "stage": "quality"
+          },
+          "github-actions": {
+            "job": "ci",
+            "notes": "Run the version guard in PR workflows against the base ref."
+          }
+        },
+        "description": "If semantic-release or automated versioning is enabled, block manual edits to canonical version fields in pull requests. Enforce a CI guard (and optional pre-push hook) that fails when version lines change outside the release workflow.",
+        "enforcement": "required",
+        "executionStage": "ci-pr",
+        "id": "version-guard",
+        "label": "Version Guard (Automated Releases)",
+        "severity": "error",
+        "stackHints": {
+          "csharp-dotnet": {
+            "exampleConfigFiles": [
+              "scripts/check-version-unchanged.sh",
+              ".github/workflows/ci.yml",
+              "azure-pipelines.yml"
+            ],
+            "exampleTools": [
+              "GitVersion",
+              "git"
+            ],
+            "notes": "When GitVersion or similar tooling computes versions, block manual edits to Directory.Build.props or *.csproj version fields via the version guard. Allow changes only in release automation.",
+            "optionalFiles": [
+              "Directory.Build.props",
+              "*.csproj",
+              "VERSION"
+            ],
+            "verification": "Run the guard and confirm it fails when <Version> or <VersionPrefix> changes in props/csproj files."
+          },
+          "go": {
+            "exampleConfigFiles": [
+              "scripts/check-version-unchanged.sh",
+              ".github/workflows/ci.yml",
+              "azure-pipelines.yml"
+            ],
+            "exampleTools": [
+              "goreleaser",
+              "git"
+            ],
+            "notes": "Go versioning is tag-driven; only enable the guard if you keep a VERSION file or embed version constants in code. The guard should ensure those fields are not edited manually in PRs.",
+            "optionalFiles": [
+              "VERSION"
+            ],
+            "verification": "Run the guard and confirm it fails when VERSION or version constants change outside release automation."
+          },
+          "python": {
+            "exampleConfigFiles": [
+              "scripts/check-version-unchanged.sh",
+              ".github/workflows/ci.yml",
+              "azure-pipelines.yml"
+            ],
+            "exampleTools": [
+              "semantic-release",
+              "git"
+            ],
+            "notes": "Block manual edits to version fields in pyproject.toml or setup.cfg when automated release tooling computes versions from commit history.",
+            "optionalFiles": [
+              "setup.cfg",
+              "setup.py",
+              "VERSION"
+            ],
+            "requiredFiles": [
+              "pyproject.toml"
+            ],
+            "verification": "Run the guard and confirm it fails when version lines change in pyproject.toml or setup.cfg."
+          },
+          "rust": {
+            "exampleConfigFiles": [
+              "scripts/check-version-unchanged.sh",
+              ".github/workflows/ci.yml",
+              "azure-pipelines.yml"
+            ],
+            "exampleTools": [
+              "cargo-release",
+              "semantic-release",
+              "git"
+            ],
+            "notes": "When using cargo-release or semantic-release-cargo, guard against manual edits to Cargo.toml version fields in PRs.",
+            "requiredFiles": [
+              "Cargo.toml"
+            ],
+            "verification": "Run the guard and confirm it fails when Cargo.toml version changes."
+          },
+          "typescript-js": {
+            "exampleConfigFiles": [
+              "scripts/check-version-unchanged.sh",
+              ".github/workflows/ci.yml",
+              "azure-pipelines.yml"
+            ],
+            "exampleTools": [
+              "semantic-release",
+              "git"
+            ],
+            "notes": "Add a CI step that runs scripts/check-version-unchanged.sh against the PR base ref. This blocks manual edits to package.json version when semantic-release owns versioning. Optionally wire the same script into a pre-push hook for fast feedback.",
+            "optionalFiles": [
+              "VERSION"
+            ],
+            "requiredFiles": [
+              "package.json"
+            ],
+            "verification": "Run the guard with the PR base ref (for example, origin/main) and confirm it fails when package.json version changes."
+          }
+        }
+      },
       {
         "appliesTo": {
           "stacks": [
@@ -657,6 +1021,7 @@
         },
         "description": "Use a single CI release pipeline that publishes all artifacts (GitHub releases, packages, containers) from the same canonical version source.",
         "enforcement": "required",
+        "executionStage": "release",
         "id": "unified-release-workflow",
         "label": "Unified Release Workflow",
         "severity": "error",
@@ -775,35 +1140,124 @@
         },
         "ciHints": {
           "azure-devops": {
-            "stage": "quality"
+            "notes": "Set HUSKY=0 or equivalent in release pipeline to disable hooks.",
+            "stage": "release"
           },
           "github-actions": {
-            "job": "ci"
+            "job": "release",
+            "notes": "Set HUSKY=0 or equivalent in release job to disable hooks."
           }
         },
-        "description": "Enforce structured commit messages such as Conventional Commits via commit-msg hooks and CI. This is required for deterministic versioning and changelog generation.",
+        "description": "Release automation must bypass local developer hooks (HUSKY=0, --no-verify) and rely solely on CI gates for validation. This ensures idempotent, reproducible releases that don't fail due to hook environment differences.",
         "enforcement": "required",
-        "id": "commit-linting",
-        "label": "Commit Linting",
+        "executionStage": "release",
+        "id": "release-hook-bypass",
+        "label": "Release Hook Bypass",
         "severity": "error",
         "stackHints": {
           "csharp-dotnet": {
-            "anyOfFiles": [
-              "commitlint.config.js",
-              "commitlint.config.cjs",
-              "commitlint.config.mjs",
-              "commitlint.config.json",
-              ".cz.toml"
-            ],
             "exampleConfigFiles": [
-              "commitlint.config.*",
-              ".cz.toml"
+              "azure-pipelines.yml",
+              ".github/workflows/release.yml"
             ],
             "exampleTools": [
-              "commitlint",
-              "commitizen"
+              "GitVersion"
             ],
-            "notes": "Document your Conventional Commit convention and enforce it via commit-msg hooks and CI so release tooling can compute versions deterministically.",
+            "notes": "Release pipelines should skip local hooks. If using Lefthook, set LEFTHOOK=0. Rely on CI gates for all validation.",
+            "verification": "Check release pipeline for hook bypass configuration."
+          },
+          "go": {
+            "exampleConfigFiles": [
+              ".goreleaser.yml",
+              ".github/workflows/release.yml"
+            ],
+            "exampleTools": [
+              "goreleaser"
+            ],
+            "notes": "Goreleaser handles releases without invoking local hooks. Ensure any git operations use --no-verify.",
+            "verification": "Check release workflow for hook bypass configuration."
+          },
+          "python": {
+            "exampleConfigFiles": [
+              ".github/workflows/release.yml"
+            ],
+            "exampleTools": [
+              "semantic-release",
+              "bumpversion"
+            ],
+            "notes": "Set PRE_COMMIT_ALLOW_NO_CONFIG=1 or SKIP=all to bypass pre-commit hooks in release automation. CI gates already validated.",
+            "verification": "Check release workflow for pre-commit bypass."
+          },
+          "rust": {
+            "exampleConfigFiles": [
+              ".github/workflows/release.yml"
+            ],
+            "exampleTools": [
+              "cargo-release"
+            ],
+            "notes": "Use --no-verify with git commands in release scripts. If using pre-commit, set SKIP=all.",
+            "verification": "Check release workflow for hook bypass."
+          },
+          "typescript-js": {
+            "exampleConfigFiles": [
+              ".github/workflows/release.yml"
+            ],
+            "exampleTools": [
+              "semantic-release",
+              "husky"
+            ],
+            "machineCheck": {
+              "command": "grep -r 'HUSKY=0\\|--no-verify' .github/workflows/ || echo 'WARNING: No hook bypass in release workflow'",
+              "description": "Verify release workflows disable hooks",
+              "expectExitCode": 0
+            },
+            "notes": "In release workflows, set HUSKY=0 environment variable to disable husky hooks. Release commits from semantic-release should bypass commitlint since they're generated. CI gates already validated the code.",
+            "verification": "Check release workflow for HUSKY=0 or --no-verify flags."
+          }
+        }
+      },
+      {
+        "appliesTo": {
+          "stacks": [
+            "typescript-js",
+            "csharp-dotnet",
+            "python",
+            "rust",
+            "go"
+          ]
+        },
+        "ciHints": {
+          "azure-devops": {
+            "stage": "quality"
+          },
+          "github-actions": {
+            "job": "ci"
+          }
+        },
+        "description": "Enforce structured commit messages such as Conventional Commits via commit-msg hooks and CI. This is required for deterministic versioning and changelog generation.",
+        "enforcement": "required",
+        "executionStage": "pre-commit",
+        "id": "commit-linting",
+        "label": "Commit Linting",
+        "severity": "error",
+        "stackHints": {
+          "csharp-dotnet": {
+            "anyOfFiles": [
+              "commitlint.config.js",
+              "commitlint.config.cjs",
+              "commitlint.config.mjs",
+              "commitlint.config.json",
+              ".cz.toml"
+            ],
+            "exampleConfigFiles": [
+              "commitlint.config.*",
+              ".cz.toml"
+            ],
+            "exampleTools": [
+              "commitlint",
+              "commitizen"
+            ],
+            "notes": "Document your Conventional Commit convention and enforce it via commit-msg hooks and CI so release tooling can compute versions deterministically.",
             "requiredScripts": [
               "commitlint"
             ],
@@ -916,6 +1370,7 @@
         },
         "description": "Generate readable unit test and coverage reports and enforce a minimum coverage threshold (around 80%) for new or changed code.",
         "enforcement": "required",
+        "executionStage": "ci-pr",
         "id": "unit-test-reporter",
         "label": "Unit Test Reporter / Coverage",
         "severity": "error",
@@ -1030,6 +1485,7 @@
         },
         "description": "Single CI pipeline that runs linting, formatting, type checking, tests, coverage, build, and containerization.",
         "enforcement": "required",
+        "executionStage": "ci-pr",
         "id": "ci-quality-gates",
         "label": "CI Quality Gates",
         "severity": "error",
@@ -1136,8 +1592,10 @@
         },
         "description": "Automatic code formatting to maintain a consistent style across all contributors.",
         "enforcement": "required",
+        "executionStage": "pre-commit",
         "id": "code-formatter",
         "label": "Code Formatter",
+        "scopeToChangedFiles": true,
         "severity": "error",
         "stackHints": {
           "csharp-dotnet": {
@@ -1236,27 +1694,33 @@
         },
         "ciHints": {
           "azure-devops": {
+            "notes": "Hooks and CI must invoke identical verification commands. Use npm run verify or equivalent.",
             "stage": "quality"
           },
           "github-actions": {
-            "job": "ci"
+            "job": "ci",
+            "notes": "Hooks and CI must invoke identical verification commands. Use npm run verify or equivalent."
           }
         },
-        "description": "Use git hooks to run linting, formatting, tests, and commit linting before changes are committed.",
+        "description": "Use git hooks to run linting, formatting, and commit linting before changes are committed. Hooks should CHECK by default (not auto-fix), be fast, and scope to changed files only. Use a single entry hook mechanism (e.g., Husky as entry point calling pre-commit or lint-staged).",
         "enforcement": "required",
+        "executionStage": "pre-commit",
         "id": "pre-commit-hooks",
         "label": "Pre-Commit Hooks",
+        "scopeToChangedFiles": true,
         "severity": "error",
         "stackHints": {
           "csharp-dotnet": {
             "exampleConfigFiles": [
-              "lefthook.yml"
+              "lefthook.yml",
+              ".husky/"
             ],
             "exampleTools": [
-              "Lefthook"
+              "Lefthook",
+              "husky.net"
             ],
-            "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."
+            "notes": "Configure Lefthook or husky.net to run formatting checks (not auto-fix) on staged files. Hooks should be deterministic and environment-pinned via global.json SDK version.",
+            "verification": "Inspect hook configuration and confirm checks run in verify mode, not auto-fix mode."
           },
           "go": {
             "exampleConfigFiles": [
@@ -1267,8 +1731,8 @@
               "pre-commit",
               "lefthook"
             ],
-            "notes": "Use pre-commit with go hooks for gofmt, goimports, and golangci-lint on staged files.",
-            "verification": "Inspect hooks configuration and confirm that go fmt and golangci-lint run before commits."
+            "notes": "Use pre-commit or lefthook with go hooks for 'gofmt -d' (check mode) and golangci-lint. Pin Go version in go.mod and .go-version for determinism.",
+            "verification": "Confirm hooks run format checks (not auto-fix) and golangci-lint before commits."
           },
           "python": {
             "exampleConfigFiles": [
@@ -1277,8 +1741,8 @@
             "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."
+            "notes": "Use pre-commit framework as both entry and executor. Pin hook versions in .pre-commit-config.yaml for determinism. Hooks should run checks (ruff check, black --check) not auto-fix. Run pre-commit install to set up hooks.",
+            "verification": "Inspect .pre-commit-config.yaml and confirm hooks use check/verify flags, not auto-fix."
           },
           "rust": {
             "exampleConfigFiles": [
@@ -1288,20 +1752,202 @@
               "pre-commit",
               "cargo-husky"
             ],
-            "notes": "Use pre-commit with rust hooks for cargo fmt and cargo clippy on staged files. cargo-husky is an alternative.",
-            "verification": "Inspect .pre-commit-config.yaml and confirm that hooks run cargo fmt --check and cargo clippy before commits."
+            "notes": "Use pre-commit with rust hooks for 'cargo fmt --check' and 'cargo clippy' on staged files. Pin rust-toolchain.toml for determinism across environments.",
+            "verification": "Confirm hooks run cargo fmt --check (not cargo fmt) and cargo clippy before commits."
           },
           "typescript-js": {
             "exampleConfigFiles": [
               ".husky/",
-              "package.json"
+              "package.json",
+              "lint-staged.config.js"
             ],
             "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."
+            "notes": "Use Husky as the entry hook mechanism calling lint-staged. Hooks should CHECK (--check flags) not auto-fix to keep developers aware of issues. Scope to staged files only for speed. Invoke hooks through the repo toolchain (npx) not global installs to ensure environment pinning. Never let hook enforcement drift from CI.",
+            "verification": "Run 'npm run verify' (or equivalent) and confirm the same checks run in both hooks and CI."
+          }
+        }
+      },
+      {
+        "appliesTo": {
+          "stacks": [
+            "typescript-js",
+            "csharp-dotnet",
+            "python",
+            "rust",
+            "go"
+          ]
+        },
+        "ciHints": {
+          "azure-devops": {
+            "notes": "CI should call the same verify script that hooks use locally.",
+            "stage": "quality"
+          },
+          "github-actions": {
+            "job": "ci",
+            "notes": "CI should call the same verify script that hooks use locally."
+          }
+        },
+        "description": "Local hooks and CI must invoke identical verification commands to prevent 'works locally, fails in CI' issues. Use a single canonical verify entrypoint (e.g., npm run verify) that both hooks and CI call.",
+        "enforcement": "required",
+        "executionStage": "pre-commit",
+        "id": "hook-ci-parity",
+        "label": "Hook/CI Parity",
+        "severity": "error",
+        "stackHints": {
+          "csharp-dotnet": {
+            "exampleConfigFiles": [
+              "Makefile",
+              "Directory.Build.props"
+            ],
+            "exampleTools": [
+              "dotnet CLI",
+              "make"
+            ],
+            "notes": "Define a verify target (make verify or dotnet cake verify) that both hooks and CI invoke. Keep verification logic in one place.",
+            "verification": "Compare hook commands with CI commands and confirm they invoke the same targets."
+          },
+          "go": {
+            "exampleConfigFiles": [
+              "Makefile",
+              "magefile.go"
+            ],
+            "exampleTools": [
+              "make",
+              "mage"
+            ],
+            "notes": "Define a verify target (make verify) that runs go vet, golangci-lint, and go test. Both hooks and CI should use this target.",
+            "verification": "Compare hook commands with CI commands and confirm they invoke the same make targets."
+          },
+          "python": {
+            "exampleConfigFiles": [
+              "Makefile",
+              "tox.ini",
+              "noxfile.py"
+            ],
+            "exampleTools": [
+              "make",
+              "tox",
+              "nox"
+            ],
+            "notes": "Define a verify target (make verify, tox -e lint, or nox -s lint) that both pre-commit and CI invoke. Pin tool versions in pyproject.toml.",
+            "verification": "Compare hook commands with CI commands and confirm they invoke the same targets."
+          },
+          "rust": {
+            "exampleConfigFiles": [
+              "Makefile",
+              "Cargo.toml"
+            ],
+            "exampleTools": [
+              "cargo",
+              "make"
+            ],
+            "notes": "Define a verify target (make verify or cargo make verify) that runs fmt --check, clippy, and test. Both hooks and CI should use this target.",
+            "verification": "Compare hook commands with CI commands and confirm they invoke the same cargo commands."
+          },
+          "typescript-js": {
+            "exampleConfigFiles": [
+              "package.json"
+            ],
+            "exampleTools": [
+              "npm scripts"
+            ],
+            "notes": "Define a 'verify' script in package.json that runs all checks (lint, format:check, typecheck). Both .husky/pre-commit and CI should call 'npm run verify'. Never add checks to CI that don't run locally.",
+            "requiredScripts": [
+              "verify"
+            ],
+            "verification": "Compare hook commands with CI commands and confirm they invoke the same scripts."
+          }
+        }
+      },
+      {
+        "appliesTo": {
+          "stacks": [
+            "typescript-js",
+            "csharp-dotnet",
+            "python",
+            "rust",
+            "go"
+          ]
+        },
+        "ciHints": {
+          "azure-devops": {
+            "notes": "Also run secret scanning in CI as a safety net for commits that bypassed hooks.",
+            "stage": "quality"
+          },
+          "github-actions": {
+            "job": "ci",
+            "notes": "Enable GitHub secret scanning and also run gitleaks in CI."
+          }
+        },
+        "description": "Scan staged diffs for credentials, API keys, and secrets before they reach the remote repository. Catch secrets at commit time rather than after they're pushed.",
+        "enforcement": "required",
+        "executionStage": "pre-commit",
+        "id": "secret-scanning-precommit",
+        "label": "Pre-commit Secret Scanning",
+        "scopeToChangedFiles": true,
+        "severity": "error",
+        "stackHints": {
+          "csharp-dotnet": {
+            "exampleConfigFiles": [
+              ".gitleaks.toml"
+            ],
+            "exampleTools": [
+              "gitleaks",
+              "detect-secrets"
+            ],
+            "notes": "Add gitleaks to pre-commit hooks via Lefthook. Scan staged changes before commits.",
+            "verification": "Run 'gitleaks protect --staged' and verify it catches test secrets."
+          },
+          "go": {
+            "exampleConfigFiles": [
+              ".gitleaks.toml",
+              ".pre-commit-config.yaml"
+            ],
+            "exampleTools": [
+              "gitleaks",
+              "trufflehog"
+            ],
+            "notes": "Add gitleaks to pre-commit hooks. Scan staged changes only for speed.",
+            "verification": "Run 'gitleaks protect --staged' and verify it catches test secrets."
+          },
+          "python": {
+            "exampleConfigFiles": [
+              ".pre-commit-config.yaml",
+              ".secrets.baseline"
+            ],
+            "exampleTools": [
+              "detect-secrets",
+              "gitleaks"
+            ],
+            "notes": "Add detect-secrets or gitleaks to .pre-commit-config.yaml. Use detect-secrets audit to manage baselines.",
+            "verification": "Run 'detect-secrets scan' or 'gitleaks protect' and verify scanning works."
+          },
+          "rust": {
+            "exampleConfigFiles": [
+              ".gitleaks.toml",
+              ".pre-commit-config.yaml"
+            ],
+            "exampleTools": [
+              "gitleaks"
+            ],
+            "notes": "Add gitleaks to pre-commit hooks. Configure Rust-specific patterns if needed.",
+            "verification": "Run 'gitleaks protect --staged' and verify it catches test secrets."
+          },
+          "typescript-js": {
+            "exampleConfigFiles": [
+              ".gitleaks.toml",
+              ".secrets.baseline"
+            ],
+            "exampleTools": [
+              "gitleaks",
+              "detect-secrets",
+              "trufflehog"
+            ],
+            "notes": "Add gitleaks or detect-secrets to pre-commit hooks. Scan only staged changes for speed. Configure allowlists for false positives in .gitleaks.toml.",
+            "verification": "Run 'gitleaks protect --staged' and verify it catches test secrets."
           }
         }
       },
@@ -1325,6 +1971,7 @@
         },
         "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.",
         "enforcement": "required",
+        "executionStage": "pre-push",
         "id": "type-checking",
         "label": "Type Checking",
         "severity": "error",
@@ -1463,6 +2110,7 @@
         },
         "description": "Lock dependencies and scan regularly for known vulnerabilities; fail CI on newly introduced high-severity issues.",
         "enforcement": "required",
+        "executionStage": "pre-push",
         "id": "dependency-security",
         "label": "Dependency Management & Vulnerability Scanning",
         "severity": "error",
@@ -1572,6 +2220,7 @@
         },
         "description": "Ensure builds are reproducible by pinning dependencies, base images, and tool/runtime versions. Avoid network/time variance and fail when lockfiles drift.",
         "enforcement": "required",
+        "executionStage": "ci-pr",
         "id": "deterministic-builds",
         "label": "Deterministic & Hermetic Builds",
         "severity": "error",
@@ -1695,6 +2344,7 @@
         },
         "description": "Produce SBOMs or provenance metadata, enable secret/code scanning, and sign tags or commits for critical repos.",
         "enforcement": "required",
+        "executionStage": "release",
         "id": "provenance-security",
         "label": "Provenance & Security Metadata",
         "severity": "error",
@@ -1815,6 +2465,7 @@
         },
         "description": "Adopt standard CI templates and config samples to scale across repositories, minimizing bespoke pipeline logic.",
         "enforcement": "required",
+        "executionStage": "ci-pr",
         "id": "ci-templates-automation",
         "label": "CI Templates & Automation",
         "severity": "error",
@@ -1936,6 +2587,7 @@
         },
         "description": "Specify required runtime/engine versions in package manifests to ensure environment stability and prevent version-related issues across development teams.",
         "enforcement": "required",
+        "executionStage": "pre-commit",
         "id": "runtime-version",
         "label": "Runtime Version Specification",
         "severity": "error",
@@ -2029,6 +2681,7 @@
         },
         "description": "Maintain a comprehensive README and, where applicable, auto-generated API docs to support onboarding and maintainability.",
         "enforcement": "required",
+        "executionStage": "ci-pr",
         "id": "documentation",
         "label": "Documentation Standards",
         "severity": "error",
@@ -2148,6 +2801,7 @@
         },
         "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.",
         "enforcement": "required",
+        "executionStage": "ci-pr",
         "id": "repository-governance",
         "label": "Repository Governance",
         "severity": "error",
@@ -2238,9 +2892,7 @@
             "verification": "LICENSE file is present in the repository root; CODE_OF_CONDUCT.md and CONTRIBUTING.md are present for contribution guidance."
           }
         }
-      }
-    ],
-    "optionalEnhancements": [
+      },
       {
         "appliesTo": {
           "stacks": [
@@ -2253,68 +2905,85 @@
         },
         "ciHints": {
           "azure-devops": {
-            "stage": "observability"
+            "notes": "CI should call the canonical verify command, not duplicate check logic.",
+            "stage": "quality"
           },
           "github-actions": {
-            "job": "ci"
+            "job": "ci",
+            "notes": "CI should call the canonical verify command, not duplicate check logic."
           }
         },
-        "description": "Standardize error handling and structured logging to make debugging and production monitoring easier.",
-        "enforcement": "optional",
-        "id": "observability",
-        "label": "Observability (Logging & Error Handling)",
-        "severity": "info",
+        "description": "Provide one canonical 'verify' command per repository/stack that all stages call with appropriate flags. This prevents duplication, drift, and ensures consistency between local development and CI.",
+        "enforcement": "required",
+        "executionStage": "pre-commit",
+        "id": "canonical-verify",
+        "label": "Canonical Verify Entrypoint",
+        "severity": "error",
         "stackHints": {
           "csharp-dotnet": {
             "exampleConfigFiles": [
-              "appsettings.json"
+              "Makefile",
+              "build.cake"
             ],
             "exampleTools": [
-              "Serilog",
-              "NLog"
+              "dotnet CLI",
+              "make",
+              "cake"
             ],
-            "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."
+            "notes": "Define 'make verify' or 'dotnet cake verify' that runs all checks. Both hooks and CI use this single entrypoint with stage-appropriate flags.",
+            "verification": "Makefile or build script contains a 'verify' target."
           },
           "go": {
-            "exampleConfigFiles": [],
+            "exampleConfigFiles": [
+              "Makefile",
+              "magefile.go"
+            ],
             "exampleTools": [
-              "slog",
-              "zap",
-              "zerolog"
+              "make",
+              "mage"
             ],
-            "notes": "Use slog (stdlib) or zap/zerolog for structured logging. Configure JSON output for production and text for development.",
-            "verification": "Confirm that a structured logging library is configured with appropriate output format and log levels."
+            "notes": "Define 'make verify' that runs go vet, golangci-lint, and go test. All stages use this single entrypoint.",
+            "verification": "Makefile contains a 'verify' target."
           },
           "python": {
             "exampleConfigFiles": [
-              "logging configuration files",
-              "pyproject.toml"
+              "Makefile",
+              "tox.ini",
+              "noxfile.py"
             ],
             "exampleTools": [
-              "structlog",
-              "loguru"
+              "make",
+              "tox",
+              "nox"
             ],
-            "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."
+            "notes": "Define 'make verify' or 'tox -e verify' that runs ruff, black --check, mypy, and pytest. All stages use this entrypoint.",
+            "verification": "Makefile or tox.ini contains a 'verify' target/environment."
           },
           "rust": {
-            "exampleConfigFiles": [],
+            "exampleConfigFiles": [
+              "Makefile",
+              "Makefile.toml"
+            ],
             "exampleTools": [
-              "tracing",
-              "log"
+              "cargo",
+              "make",
+              "cargo-make"
             ],
-            "notes": "Use the tracing crate for structured logging with spans and events. Configure tracing-subscriber for output formatting.",
-            "verification": "Confirm that tracing or log crate is configured with appropriate subscriber/logger and emits structured output."
+            "notes": "Define 'make verify' or 'cargo make verify' that runs fmt --check, clippy, and test. Both hooks and CI use this entrypoint.",
+            "verification": "Makefile or Makefile.toml contains a 'verify' task."
           },
           "typescript-js": {
-            "exampleConfigFiles": [],
+            "exampleConfigFiles": [
+              "package.json"
+            ],
             "exampleTools": [
-              "Winston",
-              "Pino"
+              "npm scripts"
             ],
-            "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."
+            "notes": "Define 'npm run verify' that runs lint, format:check, typecheck, and test. Pre-commit hooks call 'npm run verify:quick' (lint + format only). CI calls 'npm run verify' (full suite). Never duplicate verification logic across multiple scripts.",
+            "requiredScripts": [
+              "verify"
+            ],
+            "verification": "package.json contains a 'verify' script that orchestrates all checks."
           }
         }
       },
@@ -2330,15 +2999,264 @@
         },
         "ciHints": {
           "azure-devops": {
-            "stage": "governance"
+            "notes": "Ensure CI reads from authoritative configs, not duplicated settings.",
+            "stage": "quality"
           },
           "github-actions": {
-            "job": "ci"
+            "job": "ci",
+            "notes": "Ensure CI reads from authoritative configs, not duplicated settings."
           }
         },
-        "description": "Define phase transition requirements in phase-gates.md for autonomous agent workflows with clear pre-conditions and approval gates.",
-        "enforcement": "optional",
-        "id": "agent-phase-gates",
+        "description": "Each configuration rule must live in exactly one authoritative config file. Avoid duplication across .editorconfig, linter configs, and CI definitions. Document which file is authoritative for each concern.",
+        "enforcement": "required",
+        "executionStage": "ci-pr",
+        "id": "config-authority",
+        "label": "Config File Authority Rules",
+        "severity": "error",
+        "stackHints": {
+          "csharp-dotnet": {
+            "exampleConfigFiles": [
+              ".gitattributes",
+              ".editorconfig",
+              "Directory.Build.props"
+            ],
+            "exampleTools": [],
+            "notes": "Authority mapping: .gitattributes for EOL, .editorconfig for formatting rules, Directory.Build.props for shared build settings. Roslyn analyzers read from .editorconfig.",
+            "verification": "Review configs and confirm no rule is duplicated across files."
+          },
+          "go": {
+            "exampleConfigFiles": [
+              ".gitattributes",
+              "go.mod",
+              ".golangci.yml"
+            ],
+            "exampleTools": [],
+            "notes": "Authority mapping: .gitattributes for EOL, go.mod for module config and Go version, .golangci.yml for all linting rules. Keep lint config consolidated in one file.",
+            "verification": "Review configs and confirm .golangci.yml is the single source for lint rules."
+          },
+          "python": {
+            "exampleConfigFiles": [
+              ".gitattributes",
+              "pyproject.toml",
+              ".editorconfig"
+            ],
+            "exampleTools": [],
+            "notes": "Authority mapping: .gitattributes for EOL, pyproject.toml for all tool configs (ruff, black, mypy, pytest). Avoid separate tool configs (.flake8, setup.cfg) when pyproject.toml can hold them.",
+            "verification": "Review configs and confirm pyproject.toml is the single source for tool settings."
+          },
+          "rust": {
+            "exampleConfigFiles": [
+              ".gitattributes",
+              "Cargo.toml",
+              "rustfmt.toml",
+              "clippy.toml"
+            ],
+            "exampleTools": [],
+            "notes": "Authority mapping: .gitattributes for EOL, Cargo.toml for project config, rustfmt.toml for formatting, clippy.toml for linting. Each concern has one file.",
+            "verification": "Review configs and confirm no rules are duplicated across files."
+          },
+          "typescript-js": {
+            "exampleConfigFiles": [
+              ".gitattributes",
+              ".editorconfig",
+              "eslint.config.js",
+              "tsconfig.json"
+            ],
+            "exampleTools": [],
+            "notes": "Authority mapping: .gitattributes for EOL (Git layer), .editorconfig for editor display, eslint.config.js for lint rules, tsconfig.json for TS compiler options, prettier for formatting. Never duplicate rules across files.",
+            "verification": "Review configs and confirm no rule is defined in multiple places with potential for drift."
+          }
+        }
+      },
+      {
+        "appliesTo": {
+          "stacks": [
+            "typescript-js",
+            "csharp-dotnet",
+            "python",
+            "rust",
+            "go"
+          ]
+        },
+        "ciHints": {
+          "azure-devops": {
+            "notes": "CI should read skip paths from config files, not hardcode them in pipeline.",
+            "stage": "quality"
+          },
+          "github-actions": {
+            "job": "ci",
+            "notes": "CI should read skip paths from config files, not hardcode them in pipeline."
+          }
+        },
+        "description": "Encode path exclusions and skip rules deterministically in config files, not through ad-hoc human judgment. Make it clear which paths are excluded from checks and why.",
+        "enforcement": "required",
+        "executionStage": "ci-pr",
+        "id": "explicit-skip-paths",
+        "label": "Explicit Skip Paths",
+        "severity": "error",
+        "stackHints": {
+          "csharp-dotnet": {
+            "exampleConfigFiles": [
+              ".editorconfig"
+            ],
+            "exampleTools": [
+              "dotnet format",
+              "Roslyn"
+            ],
+            "notes": "Use .editorconfig file globs to exclude generated code from analysis. Document exclusions with comments.",
+            "verification": "Review .editorconfig and confirm exclusions are explicit and documented."
+          },
+          "go": {
+            "exampleConfigFiles": [
+              ".golangci.yml"
+            ],
+            "exampleTools": [
+              "golangci-lint"
+            ],
+            "notes": "Define skip-dirs and skip-files in .golangci.yml. Use //nolint comments sparingly and always include justification (//nolint:errcheck // reason).",
+            "verification": "Review .golangci.yml and confirm skip paths are explicit and documented."
+          },
+          "python": {
+            "exampleConfigFiles": [
+              "pyproject.toml"
+            ],
+            "exampleTools": [
+              "ruff",
+              "black",
+              "mypy"
+            ],
+            "notes": "Define exclude patterns in pyproject.toml [tool.ruff], [tool.black], [tool.mypy] sections. Document why each path is excluded. Avoid runtime --exclude flags.",
+            "verification": "Review pyproject.toml and confirm all exclusions are defined there, not in scripts."
+          },
+          "rust": {
+            "exampleConfigFiles": [
+              "rustfmt.toml",
+              ".clippy.toml"
+            ],
+            "exampleTools": [
+              "rustfmt",
+              "clippy"
+            ],
+            "notes": "Use #[rustfmt::skip] or #[allow(clippy::*)] sparingly and document why. For directory-level exclusions, use Cargo.toml workspace exclude.",
+            "verification": "Search for skip annotations and confirm each is documented."
+          },
+          "typescript-js": {
+            "exampleConfigFiles": [
+              ".eslintignore",
+              ".prettierignore",
+              "eslint.config.js"
+            ],
+            "exampleTools": [
+              "eslint",
+              "prettier"
+            ],
+            "notes": "Define ignores in eslint.config.js (ignores array) and .prettierignore. Document why each path is excluded (generated code, vendor, etc.). Avoid ad-hoc --ignore-path flags in scripts.",
+            "verification": "Review ignore configs and confirm all exclusions are documented and intentional."
+          }
+        }
+      }
+    ],
+    "optionalEnhancements": [
+      {
+        "appliesTo": {
+          "stacks": [
+            "typescript-js",
+            "csharp-dotnet",
+            "python",
+            "rust",
+            "go"
+          ]
+        },
+        "ciHints": {
+          "azure-devops": {
+            "stage": "observability"
+          },
+          "github-actions": {
+            "job": "ci"
+          }
+        },
+        "description": "Standardize error handling and structured logging to make debugging and production monitoring easier.",
+        "enforcement": "optional",
+        "executionStage": "ci-pr",
+        "id": "observability",
+        "label": "Observability (Logging & Error Handling)",
+        "severity": "info",
+        "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."
+          },
+          "go": {
+            "exampleConfigFiles": [],
+            "exampleTools": [
+              "slog",
+              "zap",
+              "zerolog"
+            ],
+            "notes": "Use slog (stdlib) or zap/zerolog for structured logging. Configure JSON output for production and text for development.",
+            "verification": "Confirm that a structured logging library is configured with appropriate output format and log levels."
+          },
+          "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."
+          },
+          "rust": {
+            "exampleConfigFiles": [],
+            "exampleTools": [
+              "tracing",
+              "log"
+            ],
+            "notes": "Use the tracing crate for structured logging with spans and events. Configure tracing-subscriber for output formatting.",
+            "verification": "Confirm that tracing or log crate is configured with appropriate subscriber/logger and emits structured output."
+          },
+          "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."
+          }
+        }
+      },
+      {
+        "appliesTo": {
+          "stacks": [
+            "typescript-js",
+            "csharp-dotnet",
+            "python",
+            "rust",
+            "go"
+          ]
+        },
+        "ciHints": {
+          "azure-devops": {
+            "stage": "governance"
+          },
+          "github-actions": {
+            "job": "ci"
+          }
+        },
+        "description": "Define phase transition requirements in phase-gates.md for autonomous agent workflows with clear pre-conditions and approval gates.",
+        "enforcement": "optional",
+        "executionStage": "ci-pr",
+        "id": "agent-phase-gates",
         "label": "Agent Phase Gates",
         "severity": "info",
         "stackHints": {
@@ -2419,6 +3337,7 @@
         },
         "description": "Document milestone completion criteria in victory-gates.md defining 'done' for releases and major deliverables with evidence requirements.",
         "enforcement": "optional",
+        "executionStage": "release",
         "id": "agent-victory-gates",
         "label": "Agent Victory Gates",
         "severity": "info",
@@ -2504,6 +3423,7 @@
         },
         "description": "Automate dependency updates using Renovate or Dependabot to keep dependencies current and reduce security exposure window.",
         "enforcement": "recommended",
+        "executionStage": "nightly",
         "id": "dependency-update-automation",
         "label": "Dependency Update Automation",
         "severity": "warn",
@@ -2622,6 +3542,7 @@
         },
         "description": "Enforce module boundaries and import constraints to prevent architectural drift and unwanted coupling.",
         "enforcement": "recommended",
+        "executionStage": "ci-pr",
         "id": "dependency-architecture-rules",
         "label": "Dependency Architecture Rules",
         "severity": "warn",
@@ -2720,6 +3641,7 @@
         },
         "description": "Test how components interact with each other and external systems, running after unit tests with more relaxed coverage thresholds.",
         "enforcement": "recommended",
+        "executionStage": "ci-main",
         "id": "integration-testing",
         "label": "Integration Testing",
         "severity": "warn",
@@ -2801,6 +3723,7 @@
         },
         "description": "Establish performance baselines and monitor for regressions using lightweight benchmarks or audits in CI.",
         "enforcement": "recommended",
+        "executionStage": "nightly",
         "id": "performance-baselining",
         "label": "Performance Baselines",
         "severity": "warn",
@@ -2882,6 +3805,7 @@
         },
         "description": "Measure cyclomatic complexity or similar metrics to keep code maintainable, starting as a warning-only check.",
         "enforcement": "recommended",
+        "executionStage": "ci-pr",
         "id": "complexity-analysis",
         "label": "Complexity Analysis",
         "severity": "warn",
@@ -2963,6 +3887,7 @@
         },
         "description": "Run accessibility checks on web-facing components to detect critical issues and improve inclusive UX.",
         "enforcement": "recommended",
+        "executionStage": "ci-pr",
         "id": "accessibility-auditing",
         "label": "Accessibility Auditing",
         "severity": "warn",
@@ -3013,6 +3938,442 @@
           }
         }
       },
+      {
+        "appliesTo": {
+          "stacks": [
+            "typescript-js",
+            "csharp-dotnet",
+            "python",
+            "rust",
+            "go"
+          ]
+        },
+        "ciHints": {
+          "azure-devops": {
+            "notes": "Run AI drift detection in a scheduled nightly pipeline separate from main CI.",
+            "stage": "nightly"
+          },
+          "github-actions": {
+            "job": "nightly",
+            "notes": "Use scheduled workflow (cron) to run AI drift detection nightly."
+          }
+        },
+        "description": "Run nightly or scheduled checks comparing AI-generated outputs against pinned baselines to detect model drift, prompt drift, or code changes affecting AI behavior. Attribute regressions to code changes vs model updates vs prompt changes.",
+        "enforcement": "recommended",
+        "executionStage": "nightly",
+        "id": "ai-drift-detection",
+        "label": "AI Drift Detection",
+        "severity": "warn",
+        "stackHints": {
+          "csharp-dotnet": {
+            "exampleConfigFiles": [
+              "*.verified.txt",
+              "ai-baselines/"
+            ],
+            "exampleTools": [
+              "Verify",
+              "custom baseline tests"
+            ],
+            "notes": "Use Verify library or custom comparison tests to detect AI output drift. Run nightly to catch model-side changes that don't show up in code diffs.",
+            "verification": "Run AI baseline tests and confirm outputs match pinned baselines."
+          },
+          "go": {
+            "exampleConfigFiles": [
+              "testdata/golden/",
+              "ai-baselines/"
+            ],
+            "exampleTools": [
+              "go test",
+              "golden files"
+            ],
+            "notes": "Use golden file testing pattern for AI outputs. Compare current output against pinned baselines nightly.",
+            "verification": "Run golden tests and confirm AI outputs match baselines."
+          },
+          "python": {
+            "exampleConfigFiles": [
+              "tests/ai_baselines/",
+              "pytest.ini"
+            ],
+            "exampleTools": [
+              "pytest",
+              "deepdiff",
+              "great_expectations"
+            ],
+            "notes": "Create golden output tests for AI-generated content. Use deepdiff for structured comparison. For ML models, also track metrics drift (accuracy, latency) not just output drift.",
+            "verification": "Run AI baseline tests nightly and confirm outputs match or drift is documented."
+          },
+          "rust": {
+            "exampleConfigFiles": [
+              "snapshots/",
+              "ai-baselines/"
+            ],
+            "exampleTools": [
+              "insta",
+              "custom baseline tests"
+            ],
+            "notes": "Use insta for snapshot testing of AI outputs. Pin model versions and prompt templates. Run nightly to detect drift.",
+            "verification": "Run 'cargo insta test' and confirm AI outputs match baselines."
+          },
+          "typescript-js": {
+            "exampleConfigFiles": [
+              "__snapshots__/",
+              "ai-baselines/"
+            ],
+            "exampleTools": [
+              "jest snapshots",
+              "custom baseline comparator"
+            ],
+            "notes": "Pin AI outputs as baseline snapshots. Nightly runs compare current outputs against baselines. When drift detected, investigate: was it a code change, model update, or prompt change? Log model version, prompt hash, and code SHA for attribution.",
+            "verification": "Run AI baseline tests and confirm outputs match pinned baselines or drift is intentional."
+          }
+        }
+      },
+      {
+        "appliesTo": {
+          "stacks": [
+            "typescript-js",
+            "csharp-dotnet",
+            "python",
+            "rust",
+            "go"
+          ]
+        },
+        "ciHints": {
+          "azure-devops": {
+            "notes": "Run schema validation tests as part of quality gates.",
+            "stage": "quality"
+          },
+          "github-actions": {
+            "job": "ci",
+            "notes": "Include AI output schema validation in CI test suite."
+          }
+        },
+        "description": "Validate all AI-generated outputs against strict JSON schemas or type definitions at system boundaries. Reject invalid outputs early rather than letting malformed data propagate through the system.",
+        "enforcement": "recommended",
+        "executionStage": "ci-pr",
+        "id": "ai-schema-enforcement",
+        "label": "AI Output Schema Enforcement",
+        "severity": "warn",
+        "stackHints": {
+          "csharp-dotnet": {
+            "exampleConfigFiles": [
+              "*.schema.json",
+              "Schemas/"
+            ],
+            "exampleTools": [
+              "System.Text.Json",
+              "FluentValidation",
+              "JsonSchema.Net"
+            ],
+            "notes": "Use strongly-typed DTOs with validation attributes or FluentValidation for AI outputs. Deserialize with strict settings that reject unknown properties.",
+            "verification": "Review AI integration code and confirm outputs are validated against schemas."
+          },
+          "go": {
+            "exampleConfigFiles": [
+              "schemas/"
+            ],
+            "exampleTools": [
+              "go-playground/validator",
+              "gojsonschema"
+            ],
+            "notes": "Define struct tags for JSON unmarshaling and use validator for additional constraints. Reject AI outputs that don't match expected schema.",
+            "verification": "Review AI integration code and confirm schema validation is in place."
+          },
+          "python": {
+            "exampleConfigFiles": [
+              "schemas/",
+              "models.py"
+            ],
+            "exampleTools": [
+              "pydantic",
+              "jsonschema",
+              "marshmallow"
+            ],
+            "notes": "Use Pydantic models for AI output validation. Enable strict mode to reject extra fields. Define clear schemas at system boundaries where AI outputs enter the codebase.",
+            "verification": "Review AI integration code and confirm Pydantic or equivalent validation is in place."
+          },
+          "rust": {
+            "exampleConfigFiles": [
+              "src/schemas/"
+            ],
+            "exampleTools": [
+              "serde",
+              "jsonschema",
+              "validator"
+            ],
+            "notes": "Use serde with #[serde(deny_unknown_fields)] for strict deserialization of AI outputs. Add validator derives for business rule validation.",
+            "verification": "Review AI integration code and confirm strict deserialization is enforced."
+          },
+          "typescript-js": {
+            "exampleConfigFiles": [
+              "src/schemas/",
+              "*.schema.json"
+            ],
+            "exampleTools": [
+              "zod",
+              "ajv",
+              "TypeScript"
+            ],
+            "notes": "Define strict schemas for AI outputs using Zod or JSON Schema. Parse and validate AI responses at integration boundaries. Fail fast on schema violations rather than handling partial/invalid data.",
+            "verification": "Review AI integration code and confirm all AI outputs are validated against schemas."
+          }
+        }
+      },
+      {
+        "appliesTo": {
+          "stacks": [
+            "typescript-js",
+            "csharp-dotnet",
+            "python",
+            "rust",
+            "go"
+          ]
+        },
+        "ciHints": {
+          "azure-devops": {
+            "notes": "Run AI golden tests as part of the test stage.",
+            "stage": "test"
+          },
+          "github-actions": {
+            "job": "ci",
+            "notes": "Include AI golden contract tests in CI test suite."
+          }
+        },
+        "description": "Validate AI tool-generated patches, configs, and code against exact expected formats. Test that AI outputs respect forbidden paths, file patterns, and format constraints through golden contract tests.",
+        "enforcement": "recommended",
+        "executionStage": "ci-pr",
+        "id": "ai-golden-tests",
+        "label": "AI Golden Contract Tests",
+        "severity": "warn",
+        "stackHints": {
+          "csharp-dotnet": {
+            "exampleConfigFiles": [
+              "TestData/",
+              "*.verified.json"
+            ],
+            "exampleTools": [
+              "xUnit",
+              "Verify"
+            ],
+            "notes": "Use Verify for golden file testing of AI outputs. Ensure AI-generated code respects namespace conventions and doesn't modify protected files.",
+            "verification": "Run golden tests and confirm AI outputs match verified snapshots."
+          },
+          "go": {
+            "exampleConfigFiles": [
+              "testdata/"
+            ],
+            "exampleTools": [
+              "go test",
+              "golden files"
+            ],
+            "notes": "Use golden file pattern for AI output testing. Verify generated code follows Go conventions and doesn't modify vendor/ or other protected paths.",
+            "verification": "Run golden tests and confirm AI outputs match expected files."
+          },
+          "python": {
+            "exampleConfigFiles": [
+              "tests/fixtures/",
+              "__snapshots__/"
+            ],
+            "exampleTools": [
+              "pytest",
+              "syrupy"
+            ],
+            "notes": "Use pytest with syrupy for snapshot testing AI outputs. Test that generated code follows project conventions and respects forbidden paths.",
+            "verification": "Run snapshot tests and confirm AI outputs match golden fixtures."
+          },
+          "rust": {
+            "exampleConfigFiles": [
+              "snapshots/"
+            ],
+            "exampleTools": [
+              "insta"
+            ],
+            "notes": "Use insta for snapshot testing AI-generated code and configs. Test format compliance and forbidden path restrictions.",
+            "verification": "Run 'cargo insta test' and confirm AI outputs match snapshots."
+          },
+          "typescript-js": {
+            "exampleConfigFiles": [
+              "__fixtures__/ai-outputs/",
+              "*.golden.json"
+            ],
+            "exampleTools": [
+              "jest",
+              "vitest"
+            ],
+            "notes": "Create golden test fixtures for AI-generated patches and configs. Test that outputs match exact formats, don't touch forbidden paths (node_modules, .git), and respect file naming conventions.",
+            "verification": "Run golden tests and confirm AI outputs match expected fixtures exactly."
+          }
+        }
+      },
+      {
+        "appliesTo": {
+          "stacks": [
+            "typescript-js",
+            "csharp-dotnet",
+            "python",
+            "rust",
+            "go"
+          ]
+        },
+        "ciHints": {
+          "azure-devops": {
+            "notes": "Run AI safety tests as part of security stage on main branch.",
+            "stage": "security"
+          },
+          "github-actions": {
+            "job": "security",
+            "notes": "Run AI safety checks on main branch merges."
+          }
+        },
+        "description": "Test AI integrations for prompt injection resistance, input sanitization, output filtering, and data exfiltration prevention. Include adversarial test cases that attempt to manipulate AI behavior.",
+        "enforcement": "recommended",
+        "executionStage": "ci-main",
+        "id": "ai-safety-checks",
+        "label": "AI Adversarial & Safety Testing",
+        "severity": "warn",
+        "stackHints": {
+          "csharp-dotnet": {
+            "exampleConfigFiles": [
+              "Tests/AiSafety/"
+            ],
+            "exampleTools": [
+              "xUnit",
+              "custom security tests"
+            ],
+            "notes": "Test prompt injection resistance and output sanitization. Ensure AI outputs are escaped/validated before use in SQL queries, command execution, or HTML rendering.",
+            "verification": "Run AI safety tests and confirm adversarial inputs are handled safely."
+          },
+          "go": {
+            "exampleConfigFiles": [
+              "ai_safety_test.go"
+            ],
+            "exampleTools": [
+              "go test",
+              "go-fuzz"
+            ],
+            "notes": "Create adversarial test cases for AI integrations. Use fuzzing to discover input handling edge cases.",
+            "verification": "Run AI safety tests and fuzz tests."
+          },
+          "python": {
+            "exampleConfigFiles": [
+              "tests/ai_safety/"
+            ],
+            "exampleTools": [
+              "pytest",
+              "hypothesis"
+            ],
+            "notes": "Use hypothesis for property-based testing of AI input handling. Test prompt injection, output sanitization, and data boundary enforcement.",
+            "verification": "Run AI safety tests including adversarial cases."
+          },
+          "rust": {
+            "exampleConfigFiles": [
+              "tests/ai_safety/"
+            ],
+            "exampleTools": [
+              "proptest",
+              "custom tests"
+            ],
+            "notes": "Use proptest for property-based testing of AI input validation. Test that malicious inputs don't escape sandboxing.",
+            "verification": "Run AI safety tests with adversarial inputs."
+          },
+          "typescript-js": {
+            "exampleConfigFiles": [
+              "tests/ai-safety/"
+            ],
+            "exampleTools": [
+              "jest",
+              "custom adversarial tests"
+            ],
+            "notes": "Create adversarial test suite with prompt injection attempts, malicious input patterns, and exfiltration scenarios. Test that AI outputs are sanitized before use in sensitive contexts (SQL, shell, HTML).",
+            "verification": "Run AI safety test suite and confirm all adversarial cases are handled safely."
+          }
+        }
+      },
+      {
+        "appliesTo": {
+          "stacks": [
+            "typescript-js",
+            "csharp-dotnet",
+            "python",
+            "rust",
+            "go"
+          ]
+        },
+        "ciHints": {
+          "azure-devops": {
+            "notes": "Verify AI provenance logging is implemented in quality checks.",
+            "stage": "quality"
+          },
+          "github-actions": {
+            "job": "ci",
+            "notes": "Check AI provenance logging implementation in CI."
+          }
+        },
+        "description": "Log AI provider, model version, prompt template version, parameters, and tool versions for all AI operations. Enable attribution of outputs to specific model+prompt combinations for debugging and compliance.",
+        "enforcement": "recommended",
+        "executionStage": "ci-pr",
+        "id": "ai-provenance-tracking",
+        "label": "AI Provenance & Audit Logging",
+        "severity": "warn",
+        "stackHints": {
+          "csharp-dotnet": {
+            "exampleConfigFiles": [
+              "AiProvenance.cs"
+            ],
+            "exampleTools": [
+              "OpenTelemetry",
+              "Serilog"
+            ],
+            "notes": "Use structured logging to capture AI call provenance. Include model version, prompt hash, and parameters in log context.",
+            "verification": "Review AI integration and confirm provenance logging is implemented."
+          },
+          "go": {
+            "exampleConfigFiles": [
+              "ai/provenance.go"
+            ],
+            "exampleTools": [
+              "slog",
+              "OpenTelemetry"
+            ],
+            "notes": "Use structured logging (slog) to capture AI provenance. Include model, prompt version, and parameters in log context.",
+            "verification": "Review AI integration and confirm provenance logging is implemented."
+          },
+          "python": {
+            "exampleConfigFiles": [
+              "ai/provenance.py"
+            ],
+            "exampleTools": [
+              "structlog",
+              "OpenTelemetry",
+              "MLflow"
+            ],
+            "notes": "Log AI provenance using structlog or MLflow tracking. For ML models, also track training data version and model artifact hash.",
+            "verification": "Review AI integration and confirm provenance is tracked."
+          },
+          "rust": {
+            "exampleConfigFiles": [
+              "src/ai/provenance.rs"
+            ],
+            "exampleTools": [
+              "tracing",
+              "OpenTelemetry"
+            ],
+            "notes": "Use tracing spans to capture AI call provenance. Include model version, prompt hash, and parameters as span attributes.",
+            "verification": "Review AI integration and confirm provenance is logged."
+          },
+          "typescript-js": {
+            "exampleConfigFiles": [
+              "src/ai/provenance.ts"
+            ],
+            "exampleTools": [
+              "OpenTelemetry",
+              "custom logging"
+            ],
+            "notes": "Log for each AI call: provider (OpenAI, Anthropic), model ID, prompt template hash/version, temperature, timestamp, request ID. Store provenance alongside outputs for debugging 'why did AI do X?'",
+            "verification": "Review AI integration code and confirm provenance is logged for all AI calls."
+          }
+        }
+      },
       {
         "appliesTo": {
           "stacks": [
@@ -3035,6 +4396,7 @@
         },
         "description": "Maintain INVARIANTS.md defining repository-wide rules that must always hold true, with machine-readable verification commands for autonomous agents.",
         "enforcement": "recommended",
+        "executionStage": "ci-pr",
         "id": "agent-invariants",
         "label": "Autonomous Agent Invariants",
         "severity": "warn",
@@ -3151,27 +4513,41 @@
     },
     "migrationGuide": [
       {
-        "description": "Start by adding pre-commit hooks and core formatting/linting so developers get fast feedback without touching CI.",
+        "description": "Configure .gitattributes for cross-platform line ending correctness and establish the canonical verify entrypoint before adding any checks. This prevents 'works locally, fails in CI' issues from day one.",
+        "focusIds": [
+          "gitattributes-eol",
+          "canonical-verify",
+          "hook-ci-parity",
+          "config-authority"
+        ],
+        "notes": "Start here to avoid debugging cryptic CRLF failures later. Use .gitattributes as the authority for EOL (not .editorconfig). Run 'git add --renormalize .' after adding .gitattributes to fix existing files.",
+        "step": 0,
+        "title": "Foundation: Line Endings and Hook Entry Point"
+      },
+      {
+        "description": "Add pre-commit hooks with secret scanning, formatting, and linting. Hooks should CHECK (not auto-fix) and scope to changed files only for speed.",
         "focusIds": [
           "pre-commit-hooks",
+          "secret-scanning-precommit",
           "linting",
           "code-formatter"
         ],
-        "notes": "Keep hooks fast and focused on changed files to avoid slowing down day-to-day work.",
+        "notes": "Keep hooks fast by scoping to staged files. Use Husky as entry point calling lint-staged or pre-commit. Hooks should check, not fix, to keep developers aware of issues.",
         "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.",
+        "description": "Introduce CI quality gates that mirror local hooks exactly. Add CRLF detection early in pipeline. Treat existing violations as warnings where possible.",
         "focusIds": [
+          "crlf-detection",
           "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.",
+        "notes": "CI must call the same verify scripts that hooks use. Add CRLF detection before other checks to fail fast on line ending issues. Use diff-based tools so only new violations break builds.",
         "step": 2,
-        "title": "Mirror Local Checks in CI (Soft-Fail on Legacy)"
+        "title": "Mirror Local Checks in CI with CRLF Detection"
       },
       {
         "description": "Enable type-checking, coverage thresholds, and dependency/vulnerability scanning with gradual enforcement.",
@@ -3196,9 +4572,22 @@
           "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.",
+        "notes": "Tackle recommended items in order of business value; backend-only repos can skip web-focused checks like accessibility.",
         "step": 4,
         "title": "Layer in Docs, Governance, and Recommended Checks"
+      },
+      {
+        "description": "For repos using or building with generative AI, add drift detection, schema enforcement, golden contract tests, safety testing, and provenance tracking.",
+        "focusIds": [
+          "ai-drift-detection",
+          "ai-schema-enforcement",
+          "ai-golden-tests",
+          "ai-safety-checks",
+          "ai-provenance-tracking"
+        ],
+        "notes": "Skip this step if your repo has no AI/ML components. For AI-heavy repos: add nightly drift detection to catch model changes, enforce strict schemas at AI output boundaries, and log provenance for debugging 'why did AI do X?'",
+        "step": 5,
+        "title": "AI/ML Governance (If Applicable)"
       }
     ],
     "qualityGatePolicy": {
@@ -3228,5 +4617,5 @@
       "languageFamily": "js"
     }
   },
-  "version": 4
+  "version": 5
 }