@oddessentials/repo-standards 4.3.0 → 5.0.0

package/dist/config/standards.typescript-js.azure-devops.json

@@ -1,6 +1,64 @@
 {
   "checklist": {
     "core": [
+      {
+        "ciHints": {
+          "azure-devops": {
+            "notes": "Run CRLF detection early in pipeline before other checks.",
+            "stage": "quality"
+          }
+        },
+        "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.*\\.(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."
+        }
+      },
+      {
+        "ciHints": {
+          "azure-devops": {
+            "notes": "Run CRLF detection as the first quality check before linting or testing.",
+            "stage": "quality"
+          }
+        },
+        "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.*\\.(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."
+        }
+      },
       {
         "ciHints": {
           "azure-devops": {
@@ -199,6 +257,33 @@
           "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"
+          }
+        },
+        "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",
+            "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."
+        }
+      },
       {
         "ciHints": {
           "azure-devops": {
@@ -313,23 +398,73 @@
       {
         "ciHints": {
           "azure-devops": {
+            "notes": "Hooks and CI must invoke identical verification commands. Use npm run verify or equivalent.",
             "stage": "quality"
           }
         },
-        "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": {
           "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."
+        }
+      },
+      {
+        "ciHints": {
+          "azure-devops": {
+            "notes": "CI should call the same verify script that hooks use locally.",
+            "stage": "quality"
+          }
+        },
+        "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": [
+            "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."
+        }
+      },
+      {
+        "ciHints": {
+          "azure-devops": {
+            "notes": "Also run secret scanning in CI as a safety net for commits that bypassed hooks.",
+            "stage": "quality"
+          }
+        },
+        "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": [
+            ".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."
         }
       },
       {
@@ -559,6 +694,76 @@
           ],
           "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"
+          }
+        },
+        "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": [
+            "package.json"
+          ],
+          "exampleTools": [
+            "npm scripts"
+          ],
+          "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."
+        }
+      },
+      {
+        "ciHints": {
+          "azure-devops": {
+            "notes": "Ensure CI reads from authoritative configs, not duplicated settings.",
+            "stage": "quality"
+          }
+        },
+        "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",
+            ".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."
+        }
+      },
+      {
+        "ciHints": {
+          "azure-devops": {
+            "notes": "CI should read skip paths from config files, not hardcode them in pipeline.",
+            "stage": "quality"
+          }
+        },
+        "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": [
+            ".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": [
@@ -580,6 +785,48 @@
           "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."
         }
+      },
+      {
+        "ciHints": {
+          "azure-devops": {
+            "stage": "governance"
+          }
+        },
+        "description": "Define phase transition requirements in phase-gates.md for autonomous agent workflows with clear pre-conditions and approval gates.",
+        "id": "agent-phase-gates",
+        "label": "Agent Phase Gates",
+        "stack": {
+          "exampleConfigFiles": [
+            "phase-gates.md"
+          ],
+          "exampleTools": [],
+          "notes": "Document phase transitions (Planning → Implementation → Verification → Release) with required pre-conditions, approval mechanisms, and evidence artifacts for each gate.",
+          "optionalFiles": [
+            "phase-gates.md"
+          ],
+          "verification": "phase-gates.md exists defining transition requirements between project phases."
+        }
+      },
+      {
+        "ciHints": {
+          "azure-devops": {
+            "stage": "governance"
+          }
+        },
+        "description": "Document milestone completion criteria in victory-gates.md defining 'done' for releases and major deliverables with evidence requirements.",
+        "id": "agent-victory-gates",
+        "label": "Agent Victory Gates",
+        "stack": {
+          "exampleConfigFiles": [
+            "victory-gates.md"
+          ],
+          "exampleTools": [],
+          "notes": "Define completion criteria for milestones (MVP, Beta, GA) with all required conditions, verification commands, and evidence artifacts (test reports, coverage, deployment confirmations).",
+          "optionalFiles": [
+            "victory-gates.md"
+          ],
+          "verification": "victory-gates.md exists with milestone completion criteria and evidence requirements."
+        }
       }
     ],
     "recommended": [
@@ -728,6 +975,142 @@
           "notes": "Run accessibility checks against key pages or components in CI; fail on critical violations while treating minor issues as warnings initially.",
           "verification": "For web-facing apps, run the configured accessibility tooling (for example, axe, pa11y, or Lighthouse accessibility audits) against key pages and confirm that critical issues are resolved."
         }
+      },
+      {
+        "ciHints": {
+          "azure-devops": {
+            "notes": "Run AI drift detection in a scheduled nightly pipeline separate from main CI.",
+            "stage": "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": [
+            "__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."
+        }
+      },
+      {
+        "ciHints": {
+          "azure-devops": {
+            "notes": "Run schema validation tests as part of quality gates.",
+            "stage": "quality"
+          }
+        },
+        "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": [
+            "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."
+        }
+      },
+      {
+        "ciHints": {
+          "azure-devops": {
+            "notes": "Run AI golden tests as part of the test stage.",
+            "stage": "test"
+          }
+        },
+        "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": [
+            "__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."
+        }
+      },
+      {
+        "ciHints": {
+          "azure-devops": {
+            "notes": "Run AI safety tests as part of security stage on main branch.",
+            "stage": "security"
+          }
+        },
+        "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": [
+            "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."
+        }
+      },
+      {
+        "ciHints": {
+          "azure-devops": {
+            "notes": "Verify AI provenance logging is implemented in quality checks.",
+            "stage": "quality"
+          }
+        },
+        "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": [
+            "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."
+        }
+      },
+      {
+        "ciHints": {
+          "azure-devops": {
+            "notes": "Run invariant verification commands in a dedicated quality stage.",
+            "stage": "quality"
+          }
+        },
+        "description": "Maintain INVARIANTS.md defining repository-wide rules that must always hold true, with machine-readable verification commands for autonomous agents.",
+        "id": "agent-invariants",
+        "label": "Autonomous Agent Invariants",
+        "stack": {
+          "exampleConfigFiles": [
+            "INVARIANTS.md"
+          ],
+          "exampleTools": [],
+          "notes": "Create INVARIANTS.md with a table of rules, verification commands, and severity levels. Include commands like 'npm test', 'npm run lint', 'npm run typecheck' that agents can run to validate state.",
+          "requiredFiles": [
+            "INVARIANTS.md"
+          ],
+          "verification": "INVARIANTS.md exists with machine-readable verification commands for all critical repository rules."
+        }
       }
     ]
   },
@@ -783,27 +1166,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.",
@@ -828,9 +1225,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": {