ADR: Template validation and auto-fix (adr_validate)

[rshade]

Priority: P2 - Medium Priority

Part of Epic: #289
Estimated Effort: 8-10 hours
Phase: 2 - Analysis & Validation

Problem Statement

ADRs can become inconsistent over time - missing sections, broken references, invalid statuses. Teams need automated validation to maintain ADR quality and catch issues before they accumulate.

Proposed Solution

Implement adr_validate tool that:

1. Checks all ADRs against template requirements
2. Detects broken supersession references
3. Finds orphaned ADRs (deprecated but not superseded)
4. Optionally auto-fixes common issues

Implementation Guidance

Tool Schema

const AdrValidateArgsSchema = z.object({
  directory: z.string().optional()
    .describe("Working directory"),
  strict: z.boolean().optional()
    .describe("Fail on warnings (default: false)"),
  fix: z.boolean().optional()
    .describe("Auto-fix issues where possible"),
});

Validation Rules

Errors (always fail):

• Missing required sections (Status, Context, Decision, Consequences)
• Invalid status value
• Broken supersession reference (references non-existent ADR)
• Duplicate ADR numbers

Warnings (fail in strict mode):

• Missing date
• Empty sections
• Orphaned ADRs (superseded but superseder doesn't exist)
• Very old "proposed" status (>30 days)

Info:

• ADRs that could be consolidated
• Inconsistent formatting within project

Auto-Fix Capabilities

interface FixableIssue {
  adr: number;
  issue: string;
  fix: () => Promise<void>;
}

Fixable issues:

• Missing date (add current date)
• Inconsistent status casing ("ACCEPTED" → "Accepted")
• Missing trailing newline
• Incorrect section header levels

Development Steps

1. Codebase Analysis

   • Review lint tool patterns in src/tools/lint-tools.ts
   • Review validation patterns in project

2. Implementation

   • Define validation rule interface
   • Implement each validation rule
   • Implement auto-fix for fixable issues
   • Generate clear, actionable error messages

3. Testing Requirements

   • Test each validation rule
   • Test auto-fix functionality
   • Test strict vs non-strict mode
   • Test with real-world malformed ADRs
   • Target: 85-90%+ coverage

4. Linting & Validation

   make lint
   make test
   make build

Acceptance Criteria

Feature Complete:

• All validation rules implemented
• Clear error/warning/info classification
• Auto-fix works for fixable issues
• Strict mode fails on warnings
• Returns actionable results

Quality Gates:

• make lint passes with zero errors
• make test passes with 85-90%+ coverage
• make build completes successfully

Documentation:

• JSDoc comments for all public methods
• Document all validation rules
• Update src/instructions.md

Example Usage

// Basic validation
adr_validate({})
// Returns:
// {
//   valid: false,
//   errors: [{ adr: 3, message: "Missing Consequences section" }],
//   warnings: [{ adr: 5, message: "Missing date" }],
//   info: [{ adr: 1, message: "Proposed for >30 days" }],
//   fixable: [{ adr: 5, issue: "Missing date", canFix: true }]
// }

// Auto-fix
adr_validate({ fix: true })
// Returns: { valid: true, fixed: [{ adr: 5, issue: "Added missing date" }] }

// Strict mode (CI/CD)
adr_validate({ strict: true })
// Fails if any warnings exist

References

• Epic: Epic: Architecture Decision Records (ADR) Tooling Support #289
• Depends on: Phase 1 tools (parsing)
• Similar to: src/tools/lint-tools.ts patterns