Changelog

March 14, 2026 · View on GitHub

All notable changes to Decision Guardian will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[1.2.0] - 2026-03-15

🐛 Bug Fixes

  • BUG-001: Fixed all shipped templates using wrong JSON schema ({files, content} → {type, pattern, content_rules}) — templates now produce matches correctly
  • BUG-002: string mode now accepts singular pattern as alias for patterns array instead of silently degrading to glob-only match
  • BUG-003: json_path mode now correctly detects nested key changes made in-place using context lines alongside diff lines
  • BUG-004: --fail-on-error now correctly exits 1 on rule parse failures (errors were previously pushed to warnings[] instead of errors[])
  • BUG-006: content_rules array now supports AND logic via content_match_mode: "all" (previously always OR'd)
  • BUG-007: Documented that content matchers only scan added lines — deleted lines are intentionally not matched
  • BUG-008: Duplicate decision IDs now warned and deduplicated — first occurrence wins, subsequent duplicates are skipped
  • BUG-009: Decisions with only exclusion patterns (!) in Files now emit a warning instead of silently never matching
  • BUG-010: Decisions with invalid line_range (start > end) now throw a parse error instead of degrading to glob-only match
  • BUG-011: Decisions referencing a missing external rules file now throw a parse error instead of degrading to glob-only match
  • BUG-012: Verified telemetry endpoint is reachable and correct
  • BUG-013: Empty or whitespace-only decision files now emit a warning instead of silently succeeding

✨ New Features

  • BUG-005: Added content_match_mode: "any" | "all" to FileRule — enables AND logic across content_rules within a single file rule (default: "any", no breaking change)

[1.1.0] - 2026-02-19

🎉 Major Features

NPX CLI Package

Decision Guardian can now run locally without GitHub Actions!

  • npx decision-guardian - Run checks on your local machine
  • Multi-platform support - Works with any CI/CD system (GitLab CI, Jenkins, CircleCI, etc.)
  • Three check modes:
    • --staged - Check only staged changes (default)
    • --branch <base> - Compare against a specific branch
    • --all - Check all uncommitted changes
  • Commands:
    • check <path> - Check a specific decision file
    • checkall - Auto-discover and check all .decispher/ files
    • init [--template <name>] - Scaffold a new .decispher/ directory
    • template <name> [-o <path>] - Print or save decision file templates
    • --help - Show usage information
    • --version - Show version number
  • Colored output - Rich ANSI-formatted tables and summaries for better readability
  • Compact bundle - Single file (~430KB) with zero external dependencies at runtime

Decision File Templates

Five production-ready templates to kickstart your decision documentation:

  • basic.md - Simple glob patterns and exclusions
  • advanced-rules.md - Showcases regex, JSON path, line-range matching, and nested boolean logic
  • security.md - Hardcoded credentials detection, auth middleware enforcement
  • database.md - Migration protection, schema locks, connection pool safety
  • api.md - API versioning, endpoint protection, rate limiting

Access templates via:

npx decision-guardian template security
npx decision-guardian init --template database

Opt-in Telemetry System

Privacy-first, anonymous usage analytics to improve Decision Guardian:

  • Enabled by default - Must explicitly opt-out via DG_TELEMETRY=0 environment variable
  • Zero PII collection:
    • ❌ No source code, file contents, or decision text
    • ❌ No repo names, org names, usernames, emails, commit messages, branch names, file names, or file paths
    • ✅ Only aggregated metrics: file count, decision count, match count, duration, node version, OS, CI flag
  • Runtime blocklist - Privacy module validates every payload and throws an error if any blocked field is detected
  • Fire-and-forget - Never blocks or slows down the tool (5-second timeout)
  • 90-day retention - Data aggregated per-day on Cloudflare KV with automatic expiration
  • Self-hostable - Configure custom endpoint via DG_TELEMETRY_URL
  • Backend included - Cloudflare Worker source code provided in workers/telemetry/

SOLID Architecture Refactor

Complete internal rewrite to support multiple platforms and extensibility:

  • Platform-agnostic core - src/core/ has zero @actions/* imports
  • Dependency Inversion Principle:
    • ILogger interface - Abstracts logging (implementations for GitHub Actions and CLI)
    • ISCMProvider interface - Abstracts source control (implementations for GitHub and local git)
  • Adapter Pattern:
    • src/adapters/github/ - GitHub Actions-specific code (@actions/core, @actions/github)
    • src/adapters/local/ - Local CLI code (ANSI console, git diff execution)
  • Extensibility - Adding GitLab or Bitbucket support only requires implementing ISCMProvider
  • Separation of concerns:
    • Core engine handles decision parsing, pattern matching, rule evaluation
    • Adapters handle platform-specific I/O (logging, comments, file retrieval)
    • Entry points (main.ts, cli/index.ts) orchestrate components

Note: This is an internal architectural refactor. Existing GitHub Action workflows require zero changes.

✨ Enhancements

GitHub Action Improvements

  • "All Clear" status - Existing PR comments now update to show "All Clear ✅" when no violations are detected in subsequent commits
  • Comment lifecycle - Comments automatically revert to violation status if new changes trigger rules
  • Idempotent updates - Comments only update when decision matches change (content hash-based)
  • Self-healing - Automatically cleans up duplicate comments if conflicts occur

Core Engine Improvements

  • Decoupled metrics - MetricsCollector now provides getSnapshot() instead of directly calling @actions/core
  • Platform-agnostic logging - logStructured() now accepts an ILogger parameter
  • Split health checks:
    • src/core/health.ts - checkDecisionFileExists() (platform-agnostic)
    • src/adapters/github/health.ts - validateToken() (GitHub-specific)
  • Injected dependencies - FileMatcher, RuleEvaluator, and ContentMatchers now accept ILogger via constructor injection

Performance

  • Unchanged GitHub Action behavior - Zero regression for existing workflows (verified via regression tests)
  • Optimized CLI build - Uses @vercel/ncc for single-file distribution
  • Minimal overhead - Abstraction layers add negligible runtime cost (<1%)

📚 Documentation

New Documentation Files

  • docs/cli/CLI.md - Complete CLI reference with all commands, flags, and examples
  • docs/common/ARCHITECTURE.md - SOLID design principles, module map, data flow diagrams, extensibility guide
  • docs/common/TELEMETRY.md - Privacy policy, opt-in instructions, payload schema, architecture
  • docs/common/TEMPLATES.md - Template catalog and customization guide
  • workers/telemetry/README.md - Cloudflare Worker setup and deployment instructions

Updated Documentation

  • README.md:

    • Added CLI quickstart section
    • Added trust & safety section with explicit security guarantees
    • Added demo GIF visualization
    • Enhanced feature list with CLI and telemetry
    • Updated architecture diagram for v1.1 structure
    • Added links to new docs

  • Contributing.md:

    • Updated project structure to reflect new architecture
    • Added commit scopes for new modules (cli, telemetry, adapters)
    • Documented SOLID principles for contributors
    • Added guidelines for creating new SCM provider adapters

  • SECURITY.md:

    • Added opt-in telemetry privacy section
    • Clarified "no external network calls by default" guarantee
    • Documented blocklist enforcement for telemetry payloads

  • FEATURES_ROADMAP.md:

    • Moved CLI package from "Planned" to "v1.1.0" (Shipped)
    • Moved Decision Templates from "Planned" to "v1.1.0" (Shipped)
    • Updated GitLab/Bitbucket support status to "Architecture ready (ISCMProvider)"
    • Added v1.1 feature summary with CLI, templates, and telemetry details

  • APP_WORKING.md:

    • Updated component architecture diagram to show src/core/, src/adapters/, src/cli/, src/telemetry/
    • Documented ILogger and ISCMProvider interfaces
    • Added CLI data flow diagram
    • Updated module responsibilities for SOLID architecture

🔧 Technical Changes

Project Structure

decision-guardian/
├── src/
│   ├── core/                      # NEW: Platform-agnostic engine
│   │   ├── interfaces/            # NEW: ILogger, ISCMProvider
│   │   ├── parser.ts              # MOVED from src/
│   │   ├── matcher.ts             # MOVED + MODIFIED (ILogger injection)
│   │   ├── rule-evaluator.ts      # MOVED + MODIFIED (ILogger injection)
│   │   ├── content-matchers.ts    # MOVED + MODIFIED (ILogger injection)
│   │   ├── trie.ts                # MOVED from src/
│   │   ├── rule-parser.ts         # MOVED from src/
│   │   ├── metrics.ts             # MODIFIED (removed @actions/core, added getSnapshot())
│   │   ├── logger.ts              # MOVED + MODIFIED (ILogger-based logStructured)
│   │   ├── health.ts              # SPLIT (only checkDecisionFileExists)
│   │   ├── types.ts               # MOVED from src/
│   │   └── rule-types.ts          # MOVED from src/
│   │
│   ├── adapters/                  # NEW: Platform-specific implementations
│   │   ├── github/
│   │   │   ├── actions-logger.ts  # NEW: ILogger → @actions/core
│   │   │   ├── github-provider.ts # NEW: ISCMProvider for GitHub
│   │   │   ├── comment.ts         # MOVED from src/
│   │   │   └── health.ts          # NEW: validateToken() (GitHub-specific)
│   │   └── local/
│   │       ├── console-logger.ts  # NEW: ILogger → ANSI colors
│   │       └── local-git-provider.ts # NEW: ISCMProvider → git diff
│   │
│   ├── cli/                       # NEW: CLI entry point and commands
│   │   ├── index.ts               # NEW: #!/usr/bin/env node
│   │   ├── commands/
│   │   │   ├── check.ts           # NEW: check / checkall
│   │   │   ├── init.ts            # NEW: scaffold .decispher/
│   │   │   └── template.ts        # NEW: template output
│   │   ├── formatter.ts           # NEW: ANSI-colored tables
│   │   └── paths.ts               # NEW: Template directory resolution
│   │
│   ├── telemetry/                 # NEW: Opt-in analytics
│   │   ├── sender.ts              # NEW: Fire-and-forget HTTP sender
│   │   ├── payload.ts             # NEW: Type-safe payload builder
│   │   └── privacy.ts             # NEW: Blocklist validation
│   │
│   └── main.ts                    # MODIFIED: Uses adapters, metrics.getSnapshot()
│
├── templates/                     # NEW: Decision file templates
│   ├── basic.md
│   ├── advanced-rules.md
│   ├── security.md
│   ├── database.md
│   └── api.md
│
├── workers/telemetry/             # NEW: Cloudflare Worker backend
│   ├── worker.ts                  # NEW: POST /collect + GET /stats
│   ├── wrangler.toml              # NEW: Deployment config
│   └── README.md                  # NEW: Setup guide
│
├── docs/                          # NEW: CLI, architecture, telemetry docs
│   ├── cli/CLI.md
│   ├── common/ARCHITECTURE.md
│   ├── common/TELEMETRY.md
│   ├── common/TEMPLATES.md
│   └── common/guide_indepth.md
│   └── github/APP_WORKING.md
│
├── tests/                         # REORGANIZED and EXPANDED
│   ├── core/                      # Tests for src/core/ modules
│   ├── cli/                       # NEW: CLI command tests
│   ├── adapters/                  # NEW: Adapter tests
│   ├── telemetry/                 # NEW: Telemetry tests
│   └── fixtures/                  # Test fixtures
│
└── package.json                   # MODIFIED: Added bin, build:cli script, files array

Removed Files

All backward-compatibility shims have been removed:

  • src/parser.ts, src/matcher.ts, src/rule-evaluator.ts, etc. (moved to src/core/)
  • src/github-utils.ts (split into adapters/github/github-provider.ts and adapters/github/health.ts)
  • src/comment.ts (moved to adapters/github/comment.ts)

Build System

  • New script: npm run build:cli - Bundles CLI to dist/cli/index.js (~430KB)
  • Updated package.json:
    • Added bin entry for decision-guardian CLI
    • Added files array for npm publishing (includes dist/, templates/, README.md, LICENSE)
    • Updated build targets for both Action and CLI

🧪 Testing

New Test Suites

  • tests/cli/check.test.ts - CLI check/checkall commands
  • tests/cli/init.test.ts - Directory scaffolding
  • tests/cli/template.test.ts - Template output (validates all 5 templates)
  • tests/adapters/actions-logger.test.ts - ILogger contract compliance
  • tests/adapters/local-git-provider.test.ts - Git diff parsing, staged/branch/all modes
  • tests/telemetry/sender.test.ts - Timeout, error handling
  • tests/telemetry/payload.test.ts - Payload construction
  • tests/telemetry/privacy.test.ts - Blocklist enforcement (validates all blocked fields throw errors)

Updated Test Suites

  • ALL tests updated to import from src/core/ and src/adapters/ instead of root src/
  • ALL tests now use ILogger mocks instead of mocking @actions/core directly
  • Regression suite added to verify src/core/ has zero @actions/* imports

Test Coverage

  • Total tests: 109+ (up from 86 in v1.0)
  • Core coverage: 85%+ (parser, matcher, rule-evaluator, content-matchers, trie)
  • Adapter coverage: 80%+ (GitHub and local adapters)
  • CLI coverage: 75%+ (all commands)
  • Telemetry coverage: 90%+ (privacy blocklist is critical)

🔒 Security

Enhanced Privacy

  • Runtime blocklist enforcement - Privacy module validates payloads before sending
  • No PII in telemetry - Comprehensive list of blocked fields enforced at module boundary
  • Fire-and-forget - Telemetry never affects tool behavior or exposes errors

Existing Security Features (unchanged)

  • ✅ Path traversal protection
  • ✅ ReDoS prevention (safe-regex + VM sandbox with 5s timeout)
  • ✅ Input validation (Zod schemas)
  • ✅ Read-only access (except PR comments)

🐛 Bug Fixes

  • Fixed: Comment manager now correctly handles "All Clear" status transitions
  • Fixed: Duplicate comment cleanup is more robust (idempotent)
  • Fixed: Metrics now platform-agnostic (no accidental core.setOutput() calls in core modules)

🔄 Migration Guide

For GitHub Action Users

No changes required! v1.1 is 100% backward compatible with v1.0 workflows.

# This continues to work exactly as before
- uses: DecispherHQ/decision-guardian@v1
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    decision_file: '.decispher/decisions.md'
    fail_on_critical: true

Optional: Disable telemetry (telemetry is enabled by default)

- uses: DecispherHQ/decision-guardian@v1
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
  env:
    DG_TELEMETRY: '0'  # ← Disable anonymous usage analytics

For Local Development (NEW)

Before v1.1: Had to run GitHub Action in fork to test decision files

v1.1: Run checks locally

# Install globally
npm install -g decision-guardian

# Or use directly via npx
npx decision-guardian check .decispher/decisions.md --staged
npx decision-guardian checkall --fail-on-critical

CI/CD Integration (Non-GitHub)

# GitLab CI example
check-decisions:
  image: node:20
  script:
    - npx decision-guardian check .decispher/decisions.md --branch $CI_MERGE_REQUEST_TARGET_BRANCH_NAME --fail-on-critical

🎯 Verification Gates

All changes passed comprehensive verification:

✅ Zero GitHub Action regression

  • npm run bundle → dist/index.js behavior unchanged
  • All existing workflows continue to work
  • Existing tests pass without modification

✅ Zero @actions imports in src/core/

grep -r "@actions" src/core/  # → No results

✅ All tests pass

npm test  # → 109 tests, 23 suites, all pass

✅ CLI bundle size under target

ls -lh dist/cli/index.js  # → ~430KB (target: <500KB)

✅ CLI works without GitHub environment

unset GITHUB_TOKEN GITHUB_ACTIONS
npx decision-guardian check .decispher/decisions.md --all  # → Works

✅ Manual smoke tests

  • ✅ decision-guardian --help - Shows usage
  • ✅ decision-guardian --version - Shows version
  • ✅ decision-guardian init - Creates .decispher/decisions.md
  • ✅ decision-guardian template security - Prints template
  • ✅ decision-guardian check .decispher/decisions.md --staged - Runs check
  • ✅ decision-guardian checkall - Auto-discovers files

📦 Dependencies

No New Runtime Dependencies

All new features use built-in Node.js APIs:

  • CLI argument parsing: util.parseArgs (Node.js 18+)
  • ANSI colors: Manual escape codes (no chalk dependency)
  • Git diff: child_process.execSync (Node.js built-in)
  • HTTP telemetry: fetch (Node.js 18+)

Development Dependencies (unchanged)

  • @vercel/ncc - Already used for bundling
  • jest, typescript, eslint, prettier - No changes

🚀 Performance

Benchmarks (MacBook Pro M1, 16GB RAM)

ScenarioFilesDecisionsTime (v1.0)Time (v1.1)Change
Small PR10501.2s1.2s±0%
Medium PR1002002.8s2.9s+3%
Large PR5005008.4s8.6s+2%
Huge PR3000100034s35s+3%

Conclusion: Abstraction overhead is negligible (<5%). Performance remains excellent.

🙏 Acknowledgments

This release represents a major architectural evolution of Decision Guardian:

  • SOLID principles applied throughout for extensibility
  • Privacy-first telemetry designed with input from security engineers
  • CLI usability tested with developers unfamiliar with the tool
  • Template quality validated against real-world architectural decisions

Special thanks to early testers who provided feedback on the CLI UX and template content.

🔮 What's Next

Planned for v1.2

  • GitLab CI Support - GitLabProvider implementing ISCMProvider
  • Bitbucket Pipelines Support - BitbucketProvider implementing ISCMProvider
  • Enhanced Templates - More domain-specific templates (frontend, mobile, ML/AI)

Under Consideration

  • VS Code Extension - View decisions in-editor, pattern testing, authoring assistance
  • Web Dashboard - Visualize decision metrics, file hotspots, team insights
  • Decision Inheritance - Extends: DECISION-BASE-001 for composable rules
  • Cross-Repository Rules - Share decisions across multiple repos

See FEATURES_ROADMAP.md for full roadmap.

[1.0.0] - 2024-02-09

🎉 Initial Release

Decision Guardian launched as a GitHub Action to surface architectural decisions on Pull Requests.

Core Features

  • ✅ Markdown-based decision file format (.decispher/decisions.md)
  • ✅ Glob pattern matching with Trie optimization (O(log n))
  • ✅ Advanced JSON rule system (regex, content matching, boolean logic)
  • ✅ Automatic PR comment posting with severity grouping (Critical, Warning, Info)
  • ✅ Idempotent comment updates (hash-based change detection)
  • ✅ Large PR support (handles 3000+ files via streaming)
  • ✅ Progressive comment truncation (6-layer fallback)
  • ✅ Security hardening (path traversal protection, ReDoS prevention)
  • ✅ Performance optimizations (regex caching, parallel evaluation)

Documentation

  • README.md - Quick start, examples, configuration reference
  • Contributing.md - Development setup, coding standards
  • SECURITY.md - Trust guarantees, vulnerability reporting
  • APP_WORKING.md - Technical deep-dive
  • DECISIONS_FORMAT.md - Decision file specification
  • FEATURES_ROADMAP.md - Feature roadmap
  • decision_guardian-guide_indepth.md - Comprehensive guide
  • decision_guardian_guide_overview.md - High-level overview

Technology Stack

  • TypeScript 5.3.x
  • Node.js 20.x
  • GitHub Actions API
  • Jest (86 tests)

For full changelog history, see GitHub Releases

Version Naming Convention

  • Major (X.0.0): Breaking changes, significant architecture changes
  • Minor (1.X.0): New features, backward compatible
  • Patch (1.0.X): Bug fixes, documentation updates