@oddessentials/repo-standards 4.4.0 → 5.1.0

package/dist/config/standards.python.json

@@ -1,6 +1,72 @@
 {
   "checklist": {
     "core": [
+      {
+        "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.",
+        "id": "gitattributes-eol",
+        "label": "Git Attributes (Line Endings)",
+        "stack": {
+          "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."
+        }
+      },
+      {
+        "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.",
+        "id": "crlf-detection",
+        "label": "CRLF Detection in CI",
+        "stack": {
+          "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."
+        }
+      },
       {
         "ciHints": {
           "azure-devops": {
@@ -168,6 +234,42 @@
           "verification": "Check that the canonical version in pyproject.toml or VERSION follows SemVer and verify that the configured tool (for example, setuptools_scm or bumpversion) computes or bumps the version and generates changelog entries from commit history or fragments."
         }
       },
+      {
+        "ciHints": {
+          "azure-devops": {
+            "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.",
+        "id": "version-guard",
+        "label": "Version Guard (Automated Releases)",
+        "stack": {
+          "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."
+        }
+      },
       {
         "ciHints": {
           "azure-devops": {
@@ -202,6 +304,32 @@
           "verification": "Trigger the release pipeline and confirm all artifacts share the same version number and tag."
         }
       },
+      {
+        "ciHints": {
+          "azure-devops": {
+            "notes": "Set HUSKY=0 or equivalent in release pipeline to disable hooks.",
+            "stage": "release"
+          },
+          "github-actions": {
+            "job": "release",
+            "notes": "Set HUSKY=0 or equivalent in release job to disable hooks."
+          }
+        },
+        "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.",
+        "id": "release-hook-bypass",
+        "label": "Release Hook Bypass",
+        "stack": {
+          "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."
+        }
+      },
       {
         "ciHints": {
           "azure-devops": {
@@ -329,13 +457,15 @@
       {
         "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).",
         "id": "pre-commit-hooks",
         "label": "Pre-Commit Hooks",
         "stack": {
@@ -345,8 +475,64 @@
           "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."
+        }
+      },
+      {
+        "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.",
+        "id": "hook-ci-parity",
+        "label": "Hook/CI Parity",
+        "stack": {
+          "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."
+        }
+      },
+      {
+        "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.",
+        "id": "secret-scanning-precommit",
+        "label": "Pre-commit Secret Scanning",
+        "stack": {
+          "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."
         }
       },
       {
@@ -610,6 +796,87 @@
           ],
           "verification": "LICENSE file is present in the repository root; CODE_OF_CONDUCT.md and CONTRIBUTING.md are present for contribution guidance."
         }
+      },
+      {
+        "ciHints": {
+          "azure-devops": {
+            "notes": "CI should call the canonical verify command, not duplicate check logic.",
+            "stage": "quality"
+          },
+          "github-actions": {
+            "job": "ci",
+            "notes": "CI should call the canonical verify command, not duplicate check logic."
+          }
+        },
+        "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.",
+        "id": "canonical-verify",
+        "label": "Canonical Verify Entrypoint",
+        "stack": {
+          "exampleConfigFiles": [
+            "Makefile",
+            "tox.ini",
+            "noxfile.py"
+          ],
+          "exampleTools": [
+            "make",
+            "tox",
+            "nox"
+          ],
+          "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."
+        }
+      },
+      {
+        "ciHints": {
+          "azure-devops": {
+            "notes": "Ensure CI reads from authoritative configs, not duplicated settings.",
+            "stage": "quality"
+          },
+          "github-actions": {
+            "job": "ci",
+            "notes": "Ensure CI reads from authoritative configs, not duplicated settings."
+          }
+        },
+        "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.",
+        "id": "config-authority",
+        "label": "Config File Authority Rules",
+        "stack": {
+          "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."
+        }
+      },
+      {
+        "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.",
+        "id": "explicit-skip-paths",
+        "label": "Explicit Skip Paths",
+        "stack": {
+          "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."
+        }
       }
     ],
     "optionalEnhancements": [
@@ -844,6 +1111,142 @@
           "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."
         }
       },
+      {
+        "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.",
+        "id": "ai-drift-detection",
+        "label": "AI Drift Detection",
+        "stack": {
+          "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."
+        }
+      },
+      {
+        "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.",
+        "id": "ai-schema-enforcement",
+        "label": "AI Output Schema Enforcement",
+        "stack": {
+          "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."
+        }
+      },
+      {
+        "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.",
+        "id": "ai-golden-tests",
+        "label": "AI Golden Contract Tests",
+        "stack": {
+          "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."
+        }
+      },
+      {
+        "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.",
+        "id": "ai-safety-checks",
+        "label": "AI Adversarial & Safety Testing",
+        "stack": {
+          "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."
+        }
+      },
+      {
+        "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.",
+        "id": "ai-provenance-tracking",
+        "label": "AI Provenance & Audit Logging",
+        "stack": {
+          "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."
+        }
+      },
       {
         "ciHints": {
           "azure-devops": {
@@ -925,27 +1328,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.",
@@ -970,9 +1387,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": {
@@ -982,5 +1412,5 @@
   },
   "stack": "python",
   "stackLabel": "Python",
-  "version": 4
+  "version": 5
 }