eslint-plugin-traceability 1.7.1 → 1.8.0

package/docs/decisions/001-typescript-for-eslint-plugin.accepted.md

@@ -0,0 +1,111 @@
+---
+status: "accepted"
+date: 2025-11-15
+decision-makers: [Development Team]
+consulted: [ESLint Community Best Practices, TypeScript ESLint Documentation]
+informed: [Project Stakeholders, Future Contributors]
+---
+
+# Use TypeScript for ESLint Plugin Development
+
+## Context and Problem Statement
+
+When developing an ESLint plugin that validates code traceability annotations (@story and @req comments), we need to choose the implementation language. The plugin will perform complex Abstract Syntax Tree (AST) manipulation to analyze JavaScript/TypeScript code and validate annotation compliance. The choice between JavaScript and TypeScript affects development experience, maintainability, error prevention, and integration with the broader ESLint ecosystem.
+
+## Decision Drivers
+
+- Need for type safety when working with complex AST structures and ESLint Rule API
+- Developer experience and IDE support for plugin development
+- Integration with modern ESLint tooling and TypeScript ecosystem
+- Error prevention during AST manipulation and rule configuration
+- Long-term maintainability of the plugin codebase
+- Alignment with ESLint plugin development best practices
+- Support for advanced TypeScript-aware parsing when needed
+
+## Considered Options
+
+- TypeScript with full type definitions
+- JavaScript with JSDoc type annotations
+- Plain JavaScript without type annotations
+
+## Decision Outcome
+
+Chosen option: "TypeScript with full type definitions", because it provides the strongest type safety for complex AST manipulation, offers the best developer experience through IDE integration, aligns with modern ESLint plugin development practices, and enables seamless integration with @typescript-eslint utilities.
+
+### Consequences
+
+- Good, because TypeScript prevents runtime errors from malformed AST access patterns
+- Good, because IDE autocompletion and IntelliSense improve development velocity
+- Good, because type definitions serve as living documentation for rule APIs
+- Good, because integration with @typescript-eslint/utils provides advanced parsing capabilities
+- Good, because refactoring becomes safer as the plugin grows in complexity
+- Good, because follows established patterns in the ESLint ecosystem
+- Bad, because requires additional build step for TypeScript compilation
+- Bad, because slightly increases initial setup complexity
+- Bad, because may have learning curve for developers unfamiliar with TypeScript
+
+### Confirmation
+
+Implementation compliance will be confirmed through:
+
+- TypeScript compilation passes without errors in CI/CD pipeline
+- All plugin source files use .ts extension
+- package.json includes TypeScript as development dependency
+- tsconfig.json configured for ESLint plugin development
+- Use of @typescript-eslint/utils for AST manipulation where appropriate
+- Type definitions for all rule configurations and options
+
+## Pros and Cons of the Options
+
+### TypeScript with full type definitions
+
+TypeScript provides compile-time type checking, excellent IDE support, and strong integration with ESLint tooling ecosystem.
+
+- Good, because prevents common AST manipulation errors at compile time
+- Good, because provides excellent IDE autocompletion for ESLint Rule API
+- Good, because enables type-safe rule configuration and options validation
+- Good, because integrates seamlessly with @typescript-eslint/utils
+- Good, because self-documents code through type annotations
+- Good, because supports advanced refactoring capabilities
+- Good, because aligns with modern ESLint plugin development practices
+- Neutral, because requires TypeScript knowledge from contributors
+- Bad, because adds compilation step to development workflow
+- Bad, because increases initial project setup complexity
+
+### JavaScript with JSDoc type annotations
+
+JavaScript with JSDoc comments provides some type hints while maintaining simpler build process.
+
+- Good, because no additional build step required
+- Good, because familiar to JavaScript-only developers
+- Good, because provides basic type hints through comments
+- Neutral, because some IDE support for JSDoc types
+- Bad, because no compile-time error checking
+- Bad, because JSDoc types are not enforced or validated
+- Bad, because limited integration with @typescript-eslint type definitions
+- Bad, because refactoring support is significantly weaker
+- Bad, because AST manipulation errors only discovered at runtime
+
+### Plain JavaScript without type annotations
+
+Pure JavaScript implementation with no type system support.
+
+- Good, because simplest possible setup
+- Good, because no build step required
+- Good, because no TypeScript learning curve
+- Bad, because no type safety for complex AST manipulation
+- Bad, because no IDE autocompletion for ESLint APIs
+- Bad, because all errors discovered at runtime during testing
+- Bad, because difficult to maintain as complexity grows
+- Bad, because no integration benefits with TypeScript ecosystem
+- Bad, because poor refactoring support
+
+## More Information
+
+This decision aligns with REQ-TYPESCRIPT in story 001.0-DEV-PLUGIN-SETUP. The implementation should use @typescript-eslint/utils for AST parsing utilities and follow TypeScript ESLint plugin development patterns. The decision should be re-evaluated if TypeScript compilation becomes a significant bottleneck or if the team expertise changes significantly.
+
+Related resources:
+
+- [ESLint Plugin Development Guide](https://eslint.org/docs/latest/extend/plugins)
+- [@typescript-eslint/utils Documentation](https://typescript-eslint.io/packages/utils/)
+- [TypeScript ESLint Plugin Examples](https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/eslint-plugin/src/rules)

package/docs/decisions/002-jest-for-eslint-testing.accepted.md

@@ -0,0 +1,137 @@
+---
+status: "accepted"
+date: 2025-11-15
+decision-makers: [Development Team]
+consulted:
+  [
+    ESLint Community Best Practices,
+    Jest Documentation,
+    Vitest Documentation,
+    TypeScript ESLint Testing Patterns,
+  ]
+informed: [Project Stakeholders, Future Contributors]
+---
+
+# Use Jest for ESLint Plugin Testing
+
+## Context and Problem Statement
+
+When developing an ESLint plugin in TypeScript that outputs CommonJS modules, we need to choose a testing framework for validating ESLint rules. The plugin will use ESLint's RuleTester for rule validation and needs to test complex AST manipulation logic. The choice of testing framework affects development experience, compatibility with ESLint tooling, and alignment with ecosystem practices, particularly given the CommonJS output requirement and ESLint-specific testing patterns.
+
+## Decision Drivers
+
+- Compatibility with ESLint's RuleTester and rule testing patterns
+- Support for CommonJS module testing (plugin output format)
+- Integration with TypeScript source code testing
+- Alignment with ESLint plugin development ecosystem practices
+- Developer experience for writing and debugging tests
+- Performance and reliability of test execution
+- Support for ESLint-specific testing utilities and patterns
+- Community adoption and long-term maintenance
+
+## Considered Options
+
+- Jest with TypeScript support
+- Vitest with CommonJS configuration
+- Node.js built-in test runner with TypeScript
+
+## Decision Outcome
+
+Chosen option: "Jest with TypeScript support", because it provides native CommonJS support essential for ESLint plugin testing, seamless integration with ESLint's RuleTester, follows established patterns in the ESLint ecosystem, and offers superior tooling for ESLint rule development without requiring complex configuration workarounds.
+
+### Consequences
+
+- Good, because Jest works natively with CommonJS modules (no configuration needed)
+- Good, because ESLint's RuleTester integrates seamlessly with Jest
+- Good, because follows patterns used by @typescript-eslint and most ESLint plugins
+- Good, because excellent TypeScript support through ts-jest
+- Good, because mature ecosystem with extensive ESLint testing examples
+- Good, because built-in mocking capabilities useful for file system operations
+- Good, because snapshot testing can validate error message formats
+- Bad, because Jest is slightly heavier than newer alternatives
+- Bad, because not as fast as Vitest for some use cases
+- Neutral, because requires ts-jest dependency for TypeScript support
+
+### Confirmation
+
+Implementation compliance will be confirmed through:
+
+- Jest configuration properly set up with ts-jest transformer
+- ESLint RuleTester tests run successfully without module resolution errors
+- All tests pass in CI/CD pipeline using Jest
+- package.json scripts include Jest-based testing commands
+- Test files use Jest APIs and follow Jest patterns
+- TypeScript source files can be tested directly without compilation issues
+
+## Pros and Cons of the Options
+
+### Jest with TypeScript support
+
+Jest is the most widely used testing framework in the ESLint ecosystem with mature TypeScript integration.
+
+- Good, because native CommonJS support without configuration
+- Good, because ESLint's RuleTester designed to work with Jest
+- Good, because extensive use in @typescript-eslint project provides proven patterns
+- Good, because excellent TypeScript support via ts-jest
+- Good, because mature snapshot testing for validating rule outputs
+- Good, because built-in mocking for testing file system operations
+- Good, because extensive community knowledge and examples
+- Good, because comprehensive assertion library and testing utilities
+- Neutral, because larger bundle size than alternatives
+- Neutral, because slower startup than Vitest
+- Bad, because not as modern as newer testing frameworks
+
+### Vitest with CommonJS configuration
+
+Vitest is a modern testing framework built on Vite with fast execution but requires configuration for CommonJS.
+
+- Good, because very fast test execution and hot reloading
+- Good, because modern API and excellent DX
+- Good, because good TypeScript support out of the box
+- Good, because lighter weight than Jest
+- Neutral, because growing but smaller community than Jest
+- Bad, because requires complex configuration for CommonJS compatibility
+- Bad, because ESLint RuleTester integration not well-documented
+- Bad, because fewer examples in ESLint plugin development
+- Bad, because potential issues with CommonJS module transformation
+- Bad, because ESM-first design conflicts with CommonJS requirement
+
+### Node.js built-in test runner with TypeScript
+
+Node.js native test runner provides minimal testing without external dependencies.
+
+- Good, because no external testing dependencies
+- Good, because fast startup and execution
+- Good, because growing support in Node.js ecosystem
+- Neutral, because basic feature set may be sufficient for simple tests
+- Bad, because no built-in TypeScript support (requires compilation)
+- Bad, because no established patterns for ESLint rule testing
+- Bad, because limited assertion library (requires additional dependencies)
+- Bad, because no built-in mocking capabilities
+- Bad, because minimal tooling and IDE integration
+- Bad, because ESLint RuleTester compatibility unknown
+
+## More Information
+
+This decision supports REQ-TEST-SETUP in story 001.0-DEV-PLUGIN-SETUP. The implementation should use ts-jest for TypeScript compilation and follow patterns established by @typescript-eslint project. ESLint's RuleTester should be the primary tool for rule validation testing.
+
+Key implementation considerations:
+
+- Use ts-jest transformer for TypeScript source testing
+- Configure Jest to handle both source TypeScript and compiled CommonJS
+- Follow ESLint RuleTester patterns for rule validation
+- Include snapshot testing for error message validation
+- Set up proper mocking for file system operations
+
+This decision should be re-evaluated if:
+
+- ESLint ecosystem moves away from Jest as standard
+- CommonJS requirement changes for ESLint plugins
+- Vitest significantly improves CommonJS support
+- Team expertise with Jest becomes insufficient
+
+Related resources:
+
+- [ESLint RuleTester Documentation](https://eslint.org/docs/latest/integrate/nodejs-api#ruletester)
+- [@typescript-eslint Testing Patterns](https://github.com/typescript-eslint/typescript-eslint/tree/main/packages/eslint-plugin/tests)
+- [Jest with TypeScript Guide](https://jestjs.io/docs/getting-started#using-typescript)

package/docs/decisions/003-code-quality-ratcheting-plan.md

@@ -0,0 +1,48 @@
+---
+status: "accepted"
+date: 2025-11-16
+decision-makers: [Development Team]
+consulted: [Implementation Plan, ESLint Documentation]
+informed: [All Contributors]
+---
+
+# 003-Code Quality Ratcheting Plan
+
+## Context and Decision Drivers
+
+The project currently enforces maintainability through ESLint `max-lines-per-function` and `max-lines` rules with thresholds set to 200 lines/function and 1000 lines/file. These loose thresholds present technical debt and allow overly large functions and files, which can hinder readability, maintainability, and increase complexity over time.
+
+## Considered Options
+
+1. Adopt strict industry-standard thresholds immediately (e.g., 100 lines/function, 500 lines/file).
+2. Maintain the current loose thresholds indefinitely.
+3. Implement an incremental ratcheting plan to gradually reduce thresholds over multiple sprints.
+
+## Decision Outcome
+
+We will implement option 3: an incremental ratcheting plan to gradually reduce the ESLint thresholds:
+
+- **Sprint 0 (Now)**: Reduce `max-lines-per-function` to 150 and `max-lines` to 800.
+- **Sprint 2 (Completed 2025-11-16)**: Reduce `max-lines-per-function` to 120 and `max-lines` to 600.
+- **Sprint 4**: Reduce `max-lines-per-function` to 100 and `max-lines` to 500.
+
+Automation:
+
+- Update the ESLint configuration to enforce the new thresholds immediately.
+- Configure the CI pipeline to fail on any new violations of these rules.
+- Document the ratcheting schedule in this ADR and revisit the plan at each milestone.
+
+## Consequences
+
+- Ensures maintainability improves in manageable increments, reducing developer overhead per sprint.
+- Provides clear visibility into the schedule and expectations for code size reductions.
+- Allows refactoring efforts to be planned and executed incrementally, avoiding large-scale rewrites.
+- Guarantees continuous improvement by automating enforcement in CI.
+
+## Future Review
+
+At the end of each milestone sprint, the team will:
+
+- Review existing violations.
+- Refactor code to comply with the new thresholds.
+- Update this ADR if any adjustments to the schedule are required.

package/docs/decisions/004-automated-version-bumping-for-ci-cd.md

@@ -0,0 +1,196 @@
+---
+status: "superseded"
+date: 2025-11-17
+decision-makers: [Development Team]
+consulted:
+  [
+    npm Documentation,
+    GitHub Actions Best Practices,
+    Semantic Versioning Specification,
+  ]
+informed: [Project Stakeholders, CI/CD Pipeline Maintainers]
+superseded-by: "006-semantic-release-for-automated-publishing"
+superseded-date: "2025-11-17"
+---
+
+# Automated Version Bumping for CI/CD Publishing
+
+## Context and Problem Statement
+
+The current CI/CD pipeline attempts to publish the package to npm on every push to the main branch, but lacks any mechanism to automatically increment the package version. This causes publish failures when the same version number already exists on npm, as npm does not allow republishing the same version. The pipeline fails with errors like "You cannot publish over the previously published versions" or similar npm publish conflicts.
+
+Currently, version bumping requires manual intervention through direct package.json edits, which is error-prone, interrupts the automated delivery flow, and creates a disconnect between the continuous integration process and package publishing. This breaks the principle of continuous delivery and creates friction in the development workflow.
+
+## Decision Drivers
+
+- Need for reliable automated publishing without manual intervention
+- Prevention of npm publish failures due to version conflicts
+- Alignment with semantic versioning principles for clear change communication
+- Integration with existing CI/CD pipeline and GitHub workflow
+- Maintainability of version history and changelog automation
+- Support for different types of releases (patch, minor, major)
+- Traceability of version changes to specific commits or pull requests
+- Minimal friction for developers while maintaining version discipline
+
+## Considered Options
+
+- npm version command with automated execution in CI/CD
+- Semantic Release with automated version detection
+- Manual version bumping with CI/CD workflow triggers
+- Version bumping through GitHub Actions with npm version
+
+## Decision Outcome
+
+Chosen option: "Version Increment Without Git Commits", because it eliminates CI/CD loop complexity, requires no git write permissions, solves the immediate npm publish failures, and provides the simplest implementation while maintaining full automation.
+
+### Implementation Strategy
+
+The CI/CD pipeline will use in-memory version increments without git write-back:
+
+1. **Pre-publish Version Check**: Before attempting to publish, check if the current package.json version already exists on npm using `npm view eslint-plugin-traceability@<version>`
+2. **In-Memory Version Increment**: If the version exists on npm, increment the patch version in the pipeline workspace using `npm version patch --no-git-tag-version`
+3. **Immediate Publish**: Proceed with npm publish using the incremented version without any git operations
+4. **Pipeline Logging**: Log the version increment action for visibility and debugging
+5. **No Git Write-Back**: The incremented version exists only in the pipeline workspace and is never committed back to the repository
+
+### Primary Approach Considered
+
+**Git Write-Back with Version Commits**: Increment version in pipeline, publish to npm, then commit version changes and create git tags with `[skip ci]` to prevent recursion. This approach was rejected due to complexity concerns including git write permissions, infinite loop prevention, post-publish failure handling, and potential race conditions in concurrent pipeline runs.
+
+### Consequences
+
+- Good, because prevents all npm publish failures due to version conflicts
+- Good, because maintains fully automated delivery without any manual intervention
+- Good, because eliminates infinite CI/CD loop risks entirely
+- Good, because requires no git write permissions or credentials in CI/CD
+- Good, because uses standard npm tooling that developers understand
+- Good, because simplest possible implementation with minimal failure modes
+- Good, because each pipeline run is completely independent
+- Good, because immediate resolution to publish failures with no complexity overhead
+- Neutral, because package.json version may lag behind published npm version
+- Neutral, because developers can check published version via `npm view eslint-plugin-traceability version`
+- Bad, because does not automatically determine semantic version type (major/minor/patch)
+- Bad, because no automatic git tags or version history created
+
+### Confirmation
+
+Implementation compliance will be confirmed through:
+
+- CI/CD pipeline successfully publishes without version conflicts
+- No npm publish failures due to existing version numbers
+- No git write operations or credentials required in CI/CD
+- No infinite pipeline loops or `[skip ci]` complexity needed
+- Pipeline logs clearly show when version increments occur
+- Published npm versions can be verified via `npm view eslint-plugin-traceability versions`
+- No manual intervention required for routine publishing
+
+## Pros and Cons of the Options
+
+### Version Increment Without Git Commits
+
+In-memory version increments during pipeline execution without any git write-back operations.
+
+- Good, because eliminates all CI/CD loop complexity and infinite recursion risks
+- Good, because requires no git write permissions or credentials in CI/CD environment
+- Good, because simplest possible implementation with minimal failure modes
+- Good, because each pipeline run is completely independent with no race conditions
+- Good, because immediate resolution to npm publish failures
+- Good, because uses standard npm version tooling familiar to developers
+- Good, because no complex error handling for git operations required
+- Neutral, because package.json version may not reflect latest published version
+- Neutral, because published version always discoverable via npm registry
+- Bad, because no automatic git tags created for release tracking
+- Bad, because requires manual version management for major/minor releases
+- Bad, because no automated version commit history
+
+### Git Write-Back with Version Commits
+
+Increment version in pipeline, publish to npm, then commit version changes and create git tags.
+
+- Good, because creates proper git tags and version commits automatically
+- Good, because maintains package.json synchronization with published versions
+- Good, because provides complete version history in git repository
+- Good, because allows for automated CHANGELOG.md updates
+- Good, because follows traditional npm ecosystem patterns
+- Neutral, because requires configuration of git credentials in CI/CD
+- Neutral, because creates automated commits with CI skip directives
+- Bad, because requires complex infinite loop prevention with `[skip ci]`
+- Bad, because potential for git write failures after successful npm publish
+- Bad, because introduces race conditions in concurrent pipeline runs
+- Bad, because requires git write permissions and credential management
+- Bad, because adds multiple failure modes beyond the core publish operation
+
+### Semantic Release with automated version detection
+
+Automated semantic versioning based on commit message analysis and release automation.
+
+- Good, because fully automated semantic version determination
+- Good, because analyzes commit messages for version type
+- Good, because comprehensive release note generation
+- Good, because follows semantic versioning specification strictly
+- Good, because popular in open source ecosystem
+- Neutral, because requires standardized commit message format
+- Bad, because adds significant complexity to CI/CD pipeline
+- Bad, because requires team discipline for commit message formatting
+- Bad, because may be overkill for the current project size
+- Bad, because introduces external dependency on semantic-release tool
+- Bad, because harder to override for exceptional cases
+
+### Manual version bumping with CI/CD workflow triggers
+
+Requiring manual version increments before publishing with workflow validation.
+
+- Good, because provides full developer control over versioning
+- Good, because ensures deliberate version decisions
+- Good, because no automated commits or git history noise
+- Good, because simple to understand and implement
+- Neutral, because requires developer discipline for version management
+- Bad, because breaks continuous delivery principle
+- Bad, because requires manual intervention for every release
+- Bad, because prone to human error and forgotten version bumps
+- Bad, because does not solve the original npm publish failure problem
+- Bad, because creates friction in development workflow
+
+## More Information
+
+This decision addresses the immediate CI/CD publish failures with the simplest possible solution that eliminates complexity while maintaining full automation. The in-memory version increment approach provides immediate relief from npm publish conflicts without introducing git write-back complexity.
+
+Key implementation details:
+
+```yaml
+- name: Prepare version for publish
+  run: |
+    CURRENT_VERSION=$(node -p "require('./package.json').version")
+    echo "Current package.json version: $CURRENT_VERSION"
+
+    # Check if this version exists on npm
+    if npm view eslint-plugin-traceability@$CURRENT_VERSION version >/dev/null 2>&1; then
+      echo "Version $CURRENT_VERSION already exists on npm, incrementing..."
+      npm version patch --no-git-tag-version
+      NEW_VERSION=$(node -p "require('./package.json').version")
+      echo "Bumped version to: $NEW_VERSION"
+    else
+      echo "Version $CURRENT_VERSION is available, proceeding with publish"
+    fi
+
+- name: Publish package
+  run: npm publish --access public
+```
+
+Implementation considerations:
+
+- No git credentials or write permissions required in CI/CD
+- Version increments are logged for visibility and debugging
+- Each pipeline run operates independently with no side effects
+- Published versions remain discoverable via `npm view eslint-plugin-traceability versions`
+- Manual version bumps for major/minor releases can still be done via git commits
+- Future migration to git write-back approach remains possible if needed
+
+This decision should be re-evaluated if:
+
+- Package.json/npm version drift becomes problematic for development workflow
+- Automatic git tagging becomes a requirement for release management
+- The team adopts semantic versioning discipline requiring commit message analysis
+- Integration with automated changelog generation becomes necessary
+
+The simplicity of this approach allows for easy migration to more complex solutions later while solving the immediate problem with minimal risk and complexity.

package/docs/decisions/005-github-actions-validation-tooling.accepted.md

@@ -0,0 +1,144 @@
+---
+status: "accepted"
+date: 2025-11-17
+decision-makers: [Development Team]
+consulted:
+  [
+    GitHub Actions Documentation,
+    Super-Linter Community,
+    actionlint Documentation,
+  ]
+informed: [Project Contributors, CI/CD Pipeline Maintainers]
+---
+
+# GitHub Actions Validation Tooling Selection
+
+## Context and Problem Statement
+
+The project uses GitHub Actions for CI/CD workflows defined in `.github/workflows/`. To prevent broken GitHub Actions files from being pushed to the repository, we need to implement pre-commit validation for GitHub Actions YAML files. This validation should catch syntax errors, invalid action references, and misconfigured job dependencies before they are committed, as broken workflow files could prevent CI/CD from running at all.
+
+## Decision Drivers
+
+- Need for pre-commit validation to prevent broken GitHub Actions files from being pushed
+- Performance requirements for fast local development workflows
+- Prevention of workflow files that would break CI/CD execution
+- Integration with existing development tools and pre-commit hooks
+- Maintainability and configuration simplicity
+- Resource efficiency for local development environments
+
+## Considered Options
+
+- actionlint for pre-commit hooks only
+- actionlint for both pre-commit and CI/CD
+- Super-Linter for pre-commit hooks
+- GitHub's built-in validation only
+
+## Decision Outcome
+
+Chosen option: "actionlint for pre-commit hooks only", because it prevents broken GitHub Actions files from being pushed while maintaining fast local development workflow. Once files reach CI/CD, if the workflow runs successfully, the files are valid by definition.
+
+### Consequences
+
+- Good, because actionlint provides fast pre-commit validation without container overhead
+- Good, because prevents broken GitHub Actions files from being pushed
+- Good, because specifically designed for GitHub Actions validation
+- Good, because simple configuration and maintenance
+- Good, because no Docker dependencies for local development
+- Good, because excellent performance for pre-commit hooks
+- Good, because integrates seamlessly with existing Husky-based pre-commit hooks
+- Neutral, because CI/CD validation is unnecessary if workflows execute successfully
+- Bad, because limited to GitHub Actions validation only
+- Bad, because no security vulnerability detection in pre-commit phase
+
+### Confirmation
+
+Implementation compliance will be confirmed through:
+
+- actionlint added to Husky pre-commit hook in `.husky/pre-commit`
+- Pre-commit hook blocks commits with GitHub Actions validation errors
+- actionlint configured to validate files in `.github/workflows/`
+- Documentation updated to explain Husky-based pre-commit validation approach
+
+### Implementation Approach
+
+actionlint will be integrated into existing Husky-based pre-commit hooks by:
+
+- Installing actionlint as a development dependency
+- Adding actionlint validation to `.husky/pre-commit` hook
+- Configuring actionlint to check `.github/workflows/*.yml` files
+- Documenting the validation process for contributors
+
+## Pros and Cons of the Options
+
+### actionlint for pre-commit hooks only
+
+Lightweight, focused pre-commit validation to prevent broken GitHub Actions files.
+
+- Good, because fast execution without container overhead
+- Good, because specifically designed for GitHub Actions validation
+- Good, because no Docker dependencies for local development
+- Good, because simple configuration and maintenance
+- Good, because excellent performance for pre-commit hooks
+- Good, because prevents broken workflow files from being pushed
+- Good, because minimal tooling - only runs where validation is needed
+- Neutral, because focused scope reduces complexity
+- Neutral, because CI/CD validation unnecessary if workflows execute successfully
+- Bad, because limited to GitHub Actions validation only
+- Bad, because no security vulnerability detection in pre-commit phase
+
+### actionlint for both pre-commit and CI/CD
+
+Validation in both development and CI/CD environments.
+
+- Good, because fast execution in all environments
+- Good, because specifically designed for GitHub Actions
+- Good, because consistent validation across environments
+- Neutral, because focused scope reduces complexity
+- Bad, because unnecessary duplication - CI/CD execution validates workflow correctness
+- Bad, because adds CI/CD overhead for validation that's already proven by execution
+- Bad, because limited to GitHub Actions validation only
+
+### Super-Linter for pre-commit hooks
+
+Comprehensive linting solution for pre-commit validation.
+
+- Good, because comprehensive validation including security checks
+- Good, because validates multiple file types beyond GitHub Actions
+- Neutral, because well-maintained and widely adopted
+- Bad, because container overhead makes pre-commit hooks slow
+- Bad, because heavy resource usage for simple syntax checking
+- Bad, because Docker dependency required for local development
+- Bad, because not optimized for frequent pre-commit execution
+- Bad, because overkill for the specific problem of preventing broken workflow files
+
+### GitHub's built-in validation only
+
+Rely solely on GitHub's native workflow validation.
+
+- Good, because no additional tooling or configuration required
+- Good, because automatically available in GitHub interface
+- Good, because validated by the same system that executes workflows
+- Neutral, because basic validation is always performed
+- Bad, because no pre-commit validation for early error detection
+- Bad, because broken files can be pushed, preventing CI/CD execution
+- Bad, because errors only discovered after push to repository
+- Bad, because no local development feedback
+
+## More Information
+
+This decision focuses on solving the specific problem of preventing broken GitHub Actions files from being pushed to the repository. If CI/CD workflows execute successfully, the files are validated by definition - there's no need for redundant validation in the CI/CD pipeline itself.
+
+actionlint configuration should be added to the existing Husky pre-commit hook in `.husky/pre-commit`, targeting `.github/workflows/*.yml` files to catch syntax and configuration errors before commit.
+
+The decision should be re-evaluated if:
+
+- Security vulnerability detection becomes a requirement for pre-commit validation
+- Comprehensive multi-language linting becomes necessary for pre-commit
+- Alternative tools with better GitHub Actions-specific features emerge
+- The problem scope expands beyond preventing broken workflow files
+
+Related resources:
+
+- [actionlint Documentation](https://github.com/rhymond/actionlint)
+- [GitHub Actions Workflow Syntax](https://docs.github.com/en/actions/reference/workflow-syntax-for-github-actions)
+- [Husky Documentation](https://typicode.github.io/husky/)