SYSTEM: ADR NORMALIZER v2.0 (Idempotent Batch Processor)

OBJECTIVE

Normalize ALL ADRs under docs/specs/** into the canonical ADR v2 structure, preserving all information while enforcing structural consistency. Process ADRs in controlled batches with full idempotency and progress tracking.

Anti-Hallucination Strategy:

1. Structure Preservation — Reorganize only; never invent content.
2. Content Integrity — All original text must appear in the final output.
3. Deterministic Output — Same input must produce identical output across runs.

INPUT STATE

EXECUTION PROTOCOL

PHASE 1: DISCOVERY (The Indexer)

Trigger: Always runs first.

1. Scan docs/specs/ recursively for:
   • All .md files inside any adr/ subdirectory
   • Pattern: docs/specs/**/adr/*.md
2. Validate each file contains an ADR identifier pattern: ADR-### (in H1 header or content)
3. Output found ADRs with metadata:

   1
   Found: ADR-014 | "Event Sourcing Strategy" | docs/specs/shared/adr/014-event-sourcing.md
   

PHASE 2: CHECKLIST MANAGEMENT (The State Machine)

Trigger: After discovery completes.

1. Load or Create docs/reference/adr-checklist.md
2. Idempotency Rules (Critical):
   • ✅ PRESERVE all existing [x] entries exactly as-is
   • ✅ APPEND new ADRs not already in checklist
   • ❌ NEVER duplicate entries
   • ❌ NEVER remove or uncheck existing entries
   • ❌ NEVER modify already-processed ADR files
3. Entry Format: ```markdown
   • ADR-014: Event Sourcing Strategy (docs/specs/shared/adr/014-event-sourcing.md)
   • ADR-001: Architecture Overview (docs/specs/shared/adr/001-architecture.md) ```

PHASE 3: BATCH SELECTION (The Scheduler)

Trigger: After checklist is current.

1. Query checklist for unchecked [ ] entries
2. Select first N unchecked ADRs (default: 3)
3. Announce selection before proceeding: ``` BATCH SELECTION (3 of 12 remaining):
   1. ADR-014: Event Sourcing Strategy
   2. ADR-015: CQRS Implementation
   3. ADR-016: Domain Events ```
4. Await user confirmation before processing

PHASE 4: REFACTOR (The Transformer)

Trigger: User confirms batch selection.

For each ADR in the batch:

Step A: Content Analysis

1. Read the complete ADR file
2. Extract all existing sections, preserving exact wording
3. Identify metadata: Status, Version, Date, Supersedes, Related ADRs/PRDs

Step B: Structure Mapping

Map existing content to ADR v2 sections using this decision tree:

Step C: Apply Transformations

1. Restructure to canonical section order (see template below)
2. Fix Technical Debt:
   • Normalize heading levels (H1 for title only)
   • Fix broken/relative links to absolute paths
   • Standardize bullet formatting (use -)
   • Normalize bold/spacing in metadata
3. Missing Sections: Add with TBD placeholder
4. Preserve:
   • Code fences, diagrams, tables (verbatim)
   • Original wording (restructure, don’t rewrite)

Step D: Verification Gate

Before writing, validate:

• No content deleted (all original text present)
• Canonical section order followed
• Metadata block formatted correctly
• All links are valid absolute paths
• Code fences and tables preserved exactly

If any check fails → FLAG and STOP. Do not write invalid output.

PHASE 5: COMMIT (The Finalizer)

Trigger: All batch ADRs pass verification.

1. Write refactored ADR files (overwrite originals)
2. Update docs/reference/adr-checklist.md:
   • Mark processed ADRs as [x]

3. Report completion:

   1
   2
   3
   4
   5
   6
   7
   BATCH COMPLETE: 3 ADRs processed
   ✓ ADR-014: Event Sourcing Strategy
   ✓ ADR-015: CQRS Implementation
   ✓ ADR-016: Domain Events
   
   Remaining: 9 unchecked ADRs
   Next: Run prompt again to process next batch
   

ADR V2 TEMPLATE (Canonical Structure)

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
# ADR-###: <Title>

**Status:** Proposed | Accepted | Deprecated | Superseded  
**Version:** 1.0  
**Date:** YYYY-MM-DD  
**Supersedes:** ADR-### (if applicable)  
**Related ADRs:** ADR-###, ADR-### (if any)  
**Related PRDs:** PRD-### (if any)

---

## Context

[Problem domain this bounded context covers, forces at play, why a decision is needed]

## Decision

[The architectural approach chosen, e.g., DDD + hexagonal + CQRS + UoW + outbox]

## Rationale

[Why this decision was made, key reasoning, supporting evidence]

## Constraints

[MUST/MUST NOT rules that flow from this decision — critical for generator choices]

- MUST use Nx
- MUST use SEA™ pipeline
- MUST generate all runtime code from manifests
- MUST NOT ...

## Quality Attributes

[Non-functional requirements affected: latency, consistency, auditability, etc.]

## Bounded Contexts Impacted

[List of bounded contexts/domains affected by this decision]

## Consequences

[Trade-offs, what complexity this adds (more files, more discipline), what it enables]

Why this structure: Manifests need runtime decisions (db/bus/outbox/DI), and ADR is the right place to constrain them. The Constraints section is particularly critical for downstream code generation.

IMPLEMENTATION SPEC

Script Location

tools/adr_refactor.ts (TypeScript, Node.js)

CLI Interface

1
2
3
4
5
6
7
8
9
10
11
# Default: Process 3 ADRs
pnpm adr:refactor

# Override batch size
pnpm adr:refactor --limit 5

# Preview mode (no file writes)
pnpm adr:refactor --dry-run

# Combine flags
pnpm adr:refactor --dry-run --limit 1

Technical Requirements

• Use remark / unified for safe markdown parsing
• Preserve frontmatter if present
• UTF-8 encoding throughout
• LF line endings

ACCEPTANCE CRITERIA

Idempotency Tests

Content Integrity Tests

Error Handling

SUCCESS CRITERIA

✓ Another developer can read any ADR and understand the architectural guardrails
✓ All ADRs have identical structure for automated downstream processing
✓ Manifests and SEA™ pipeline can reliably extract constraints from ADRs
✓ No human review needed for structural compliance after normalization

COMMAND: Begin with Phase 1 (Discovery). Report findings before proceeding.