egallmann · egallmann · Mar 8, 2026 · Mar 8, 2026 · Mar 8, 2026 · Mar 8, 2026
diff --git a/.github/workflows/test.yml b/.github/workflows/test.yml
@@ -25,27 +25,23 @@ jobs:
       with:
         node-version: ${{ matrix.node-version }}
         cache: 'npm'
-        cache-dependency-path: ste-runtime/package-lock.json
+        cache-dependency-path: package-lock.json
 
     - name: Setup Python
       uses: actions/setup-python@v5
       with:
         python-version: '3.x'
 
     - name: Install dependencies
-      working-directory: ./ste-runtime
       run: npm ci
 
     - name: Build TypeScript
-      working-directory: ./ste-runtime
       run: npm run build
 
     - name: Run tests
-      working-directory: ./ste-runtime
       run: npm test
 
     - name: Verify RECON self-documentation
-      working-directory: ./ste-runtime
       run: |
         npm run recon:self
         echo "RECON self-documentation completed successfully"

diff --git a/README.md b/README.md
@@ -48,7 +48,7 @@ The complete STE Runtime system (per [STE Architecture Specification](https://gi
 - **AI-DOC Fabric** — Attestation authority and canonical state resolution
 - **STE Gateway** — Enforcement service for eligibility verification
 - **Trust Registry** — Public key distribution and signature verification
-- **CEM** (Cognitive Execution Model) — 9-stage execution lifecycle (deferred per [E-ADR-003](documentation/e-adr/E-ADR-003-CEM-Deferral.md))
+- **CEM** (Cognitive Execution Model) — 9-stage execution lifecycle (deferred per [ADR-L-0003](adrs/logical/ADR-L-0003-cem-implementation-deferral.yaml))
 - **Task Analysis Protocol** — Full natural language to entry point resolution (basic implementation exists, full protocol not implemented)
 - **Validation Stack** — CEM self-validation, static analysis, MCP validators
 
@@ -292,6 +292,12 @@ const impact = blastRadius(ctx, 'data/entity/UsersTable');
 
 ## Documentation
 
+### Architecture Decision Records
+- [Architecture Decisions](adrs/) - Machine-verifiable ADRs in ADR Kit format
+- [ADR Manifest](adrs/manifest.yaml) - Discovery index (11 ADRs, 13 invariants)
+- [Migration History](adrs/MIGRATION.md) - E-ADR to ADR Kit migration details
+- [Archived E-ADRs](documentation/e-adr-archived/) - Original exploratory ADRs (deprecated)
+
 ### Architecture
 - [System Architecture](documentation/architecture.md) - Complete technical architecture of ste-runtime
 - [Architecture Diagrams](documentation/diagrams/) - Visual architecture documentation
@@ -319,14 +325,14 @@ const impact = blastRadius(ctx, 'data/entity/UsersTable');
 ### Architecture & Design
 - [System Architecture](documentation/architecture.md) - Complete technical architecture of ste-runtime
 - [Alternatives Comparison](documentation/reference/alternatives-comparison.md) - How ste-runtime compares to tree-sitter, LSP, Kythe, Sourcegraph
-- [E-ADRs](documentation/e-adr/) - Architectural decision records
+- [Architecture Decision Records](adrs/) - ADR Kit format (machine-verifiable)
 - [Architecture Diagrams](documentation/diagrams/) - Visual architecture documentation
 - [Reference Documentation](documentation/reference/) - Technical deep-dives
 
 ### Contributing
 - [Contributing Guide](CONTRIBUTING.md) - Development standards and future contribution process
   - **Note:** External contributions are not currently being accepted. This guide is for future reference.
-- [Extractor Development Guide](documentation/e-adr/E-ADR-008-Extractor-Development-Guide.md) - Create custom extractors
+- [Extractor Development Guide](documentation/e-adr-archived/E-ADR-008-Extractor-Development-Guide.md) - Create custom extractors
 
 ---
 
@@ -431,7 +437,7 @@ ste-runtime/
 │   └── config/             # Configuration loader
 ├── python-scripts/         # Python AST parser
 ├── instructions/           # Usage guides
-├── documentation/          # E-ADRs and reference materials
+├── documentation/          # Reference materials and archived E-ADRs
 ├── fixtures/               # Test fixtures
 ├── .ste/                   # Example: Semantic state for parent project
 ├── .ste-self/              # Self-documentation (npm run recon:self)
@@ -527,7 +533,7 @@ ste-runtime is **designed to be forked and extended**. Expected use cases:
 5. **Run `npm run recon:self`** to document your changes
 6. **Use RSS** to query and validate your implementation
 
-See [documentation/e-adr/E-ADR-008-Extractor-Development-Guide.md](documentation/e-adr/E-ADR-008-Extractor-Development-Guide.md) for detailed guidance.
+See [documentation/e-adr-archived/E-ADR-008-Extractor-Development-Guide.md](documentation/e-adr-archived/E-ADR-008-Extractor-Development-Guide.md) for detailed guidance.
 
 ### Contributions to Main Repository
 

diff --git a/adrs/MIGRATION.md b/adrs/MIGRATION.md
@@ -0,0 +1,183 @@
+# E-ADR to ADR Kit Migration
+
+**Migration Date:** 2026-03-08  
+**Migrated By:** ADR Kit migration tooling  
+**Source Format:** E-ADRs (Exploratory ADRs) in Markdown  
+**Target Format:** ADR Kit v1.0 YAML+Markdown
+
+## Why Migrate?
+
+### Problems with E-ADR Format
+
+1. **Not machine-verifiable**: Markdown with pseudo-frontmatter (bold text, not YAML)
+2. **Inconsistent structure**: Free-form sections, no schema enforcement
+3. **Poor AI readability**: LLMs must parse narrative text to extract decisions
+4. **No discovery index**: Must scan all files to find relevant ADRs
+5. **Not STE-compliant**: Doesn't follow PRIME-1, PRIME-2, SYS-14
+
+### Benefits of ADR Kit Format
+
+1. **Machine-verifiable**: JSON Schema + Pydantic validation
+2. **Deterministic structure**: YAML frontmatter with strict schema
+3. **AI-first readability**: Structured data + embedded Markdown
+4. **Discoverable**: Auto-generated manifest.yaml (SYS-14: Index Currency)
+5. **STE-compliant**: Follows System of Thought Engineering principles
+6. **Graph-integrated**: RECON extracts ADRs into semantic graph
+
+## Migration Process
+
+### Phase 1: Build Migration Tooling
+
+Built in [adr-architecture-kit](https://github.com/egallmann/adr-architecture-kit):
+
+- `src/adr_kit/migrators/e_adr_parser.py` - Parse E-ADR markdown
+- `src/adr_kit/migrators/markdown_to_yaml.py` - Generate YAML ADRs
+- `src/adr_kit/migrators/e_adr_classification.py` - Classify as Logical/Physical
+- `scripts/migrate_e_adrs.py` - CLI migration tool
+
+### Phase 2: Classification
+
+**Logical ADRs (6)** - Conceptual decisions (what/why):
+- E-ADR-001 → ADR-L-0001 (RECON Provisional Execution)
+- E-ADR-002 → ADR-L-0002 (RECON Self-Validation)
+- E-ADR-003 → ADR-L-0003 (CEM Deferral)
+- E-ADR-007 → ADR-L-0004 (Watchdog Authoritative Mode)
+- E-ADR-009 → ADR-L-0005 (Self-Configuring Domain Discovery)
+- E-ADR-010 → ADR-L-0006 (Conversational Query Interface)
+
+**Physical ADRs (5)** - Implementation specs (how):
+- E-ADR-004 → ADR-P-0001 (RSS CLI)
+- E-ADR-005 → ADR-P-0002 (JSON Extraction)
+- E-ADR-006 → ADR-P-0003 (Angular/CSS Extraction)
+- E-ADR-011 → ADR-P-0004 (MCP Server)
+- E-ADR-013 → ADR-P-0005 (Extractor Validation)
+
+**Documentation (1)** - Not migrated:
+- E-ADR-008 (Extractor Development Guide) - Kept as guide, not a decision
+
+### Phase 3: Field Mapping
+
+**E-ADR Markdown → ADR Kit YAML:**
+
+```yaml
+# E-ADR Header (bold text)
+**Status:** Accepted
+**Implementation:** Complete
+**Date:** 2026-01-07
+**Author:** Erik Gallmann
+
+# Maps to ADR Kit frontmatter
+schema_version: "1.0"
+adr_type: logical  # or physical
+id: ADR-L-0001
+title: "Extracted from E-ADR title"
+status: accepted  # lowercase
+created_date: "2026-01-07"
+authors: ["erik.gallmann"]
+domains: ["recon", "architecture"]
+tags: ["recon", "provisional-execution"]
+
+# E-ADR Sections → ADR Kit fields
+Context section → context: |
+Decision section → decisions[].summary
+Rationale section → decisions[].rationale
+Specification section → invariants[] or component_specifications[]
+Consequences section → decisions[].consequences
+```
+
+### Phase 4: Reverse Engineering (Physical ADRs)
+
+For Physical ADRs, implementation details were **reverse-engineered from actual source code**:
+
+- **Technology stack**: Extracted from `package.json` and imports
+- **Component specifications**: Identified from `src/` directory structure
+- **Implementation identifiers**: Mapped to actual file paths, classes, functions
+- **Specification details**: Combined E-ADR spec with actual implementation patterns
+
+**Example (ADR-P-0004 MCP Server):**
+```yaml
+technology_stack:
+  - category: library
+    name: "@modelcontextprotocol/sdk"
+    version: "1.25.3"  # From package.json
+    rationale: "Standard MCP protocol implementation"
+
+component_specifications:
+  - id: COMP-0001
+    name: "MCP Server"
+    implementation_identifiers:
+      module_path: "src/mcp/mcp-server.ts"  # Actual file
+```
+
+This approach recognizes that ste-runtime was built with rigor - the implementation is the source of truth for Physical ADR details.
+
+### Phase 5: Validation
+
+All migrated ADRs validated successfully:
+- ✓ JSON Schema validation (0 errors)
+- ✓ Pydantic model validation (0 errors)
+- ✓ Cross-reference validation (all related_adrs exist)
+- ✓ Implementation identifiers point to real files
+
+### Phase 6: Generation
+
+Auto-generated artifacts using ADR Kit services:
+- `manifest.yaml` - Discovery index (11 ADRs, 13 invariants)
+- `rendered/*.md` - Human-readable markdown views (11 files)
+
+### Phase 7: RECON Validation
+
+Ran RECON on ste-runtime codebase to validate graph extraction:
+- ✓ 791 slices extracted from TypeScript source
+- ✓ 213 graph nodes, 312 edges
+- ✓ 0 conflicts detected
+- ✓ RSS queries work correctly
+
+## What Was Preserved?
+
+- **All narrative content**: Embedded in YAML as Markdown
+- **All metadata**: Status, dates, authors, authority
+- **All sections**: Context, Decision, Rationale, Specification, Consequences
+- **Historical record**: Original E-ADRs archived in `documentation/e-adr-archived/`
+
+## What Was Enhanced?
+
+- **Structured metadata**: YAML frontmatter with strict schema
+- **Explicit relationships**: `related_adrs`, `implements_logical` fields
+- **Invariants extracted**: 13 invariants identified from specifications
+- **Technology stack**: Reverse-engineered from package.json
+- **Component specs**: Mapped to actual implementation files
+- **Discovery index**: Manifest enables fast queries by domain, status, technology
+
+## What Was Lost?
+
+**Nothing.** Original E-ADRs are archived with full history preserved.
+
+## Accessing Original E-ADRs
+
+Original E-ADRs are archived in `documentation/e-adr-archived/` with a deprecation notice pointing to the new ADR Kit versions.
+
+## Tooling
+
+All migration tooling is available in [adr-architecture-kit](https://github.com/egallmann/adr-architecture-kit):
+
+```bash
+# Migrate other projects
+python scripts/migrate_e_adrs.py \
+  --input-dir path/to/e-adrs \
+  --output-dir path/to/adrs \
+  --ste-runtime-root path/to/project
+```
+
+## Future Migrations
+
+The migration tooling is designed to be reusable for:
+- Other Markdown ADR formats (Nygard template, ADR Tools)
+- Legacy documentation to structured ADRs
+- Cross-project ADR consolidation
+
+## References
+
+- [ADR Kit Schema](https://github.com/egallmann/adr-architecture-kit/tree/main/schema)
+- [STE Architecture Specification](../spec/ste-spec/)
+- [Original E-ADRs (archived)](../documentation/e-adr-archived/)
diff --git a/adrs/README.md b/adrs/README.md
@@ -0,0 +1,124 @@
+# ste-runtime Architecture Decision Records
+
+This directory contains ste-runtime's architecture decisions in **ADR Kit format** - a machine-verifiable, STE-compliant ADR system.
+
+## What Changed?
+
+**Previous format:** E-ADRs (Exploratory ADRs) in Markdown with pseudo-frontmatter  
+**Current format:** ADR Kit YAML+Markdown with JSON Schema validation  
+**Migration date:** 2026-03-08
+
+## Directory Structure
+
+```
+adrs/
+├── logical/          # Conceptual decisions (what/why)
+│   ├── ADR-L-0001.yaml
+│   ├── ADR-L-0002.yaml
+│   └── ...
+├── physical/         # Implementation specs (how)
+│   ├── ADR-P-0001.yaml
+│   ├── ADR-P-0002.yaml
+│   └── ...
+├── rendered/         # Auto-generated markdown views
+│   ├── ADR-L-0001.md
+│   └── ...
+├── manifest.yaml     # Auto-generated discovery index
+└── README.md         # This file
+```
+
+## ADR Types
+
+### Logical ADRs (6 total)
+Conceptual architecture decisions - the "what" and "why":
+- **ADR-L-0001**: RECON Provisional Execution
+- **ADR-L-0002**: RECON Self-Validation Strategy
+- **ADR-L-0003**: CEM Implementation Deferral
+- **ADR-L-0004**: Watchdog Authoritative Mode
+- **ADR-L-0005**: Self-Configuring Domain Discovery
+- **ADR-L-0006**: Conversational Query Interface
+
+### Physical ADRs (5 total)
+Implementation specifications - the "how":
+- **ADR-P-0001**: RSS CLI Implementation
+- **ADR-P-0002**: JSON Data Extraction
+- **ADR-P-0003**: Angular/CSS Semantic Extraction
+- **ADR-P-0004**: ste-runtime MCP Server
+- **ADR-P-0005**: Extractor Validation Requirements
+
+## Using the Manifest
+
+The `manifest.yaml` file provides fast discovery and statistics:
+
+```bash
+# Query by domain
+grep -A 5 "by_domain:" manifest.yaml
+
+# Query by technology
+grep -A 10 "by_technology:" manifest.yaml
+
+# View statistics
+grep -A 10 "statistics:" manifest.yaml
+```
+
+**Key statistics:**
+- Total ADRs: 11
+- Logical ADRs: 6
+- Physical ADRs: 5
+- Total Invariants: 13
+
+## ADR Kit Schema
+
+ADRs follow the [ADR Kit v1.0 schema](https://github.com/egallmann/adr-architecture-kit):
+
+- **YAML frontmatter** for machine-readable metadata
+- **Embedded Markdown** for human-readable prose
+- **JSON Schema validation** for structural correctness
+- **Pydantic models** for programmatic access
+- **STE-compliant** (PRIME-1, PRIME-2, SYS-2, SYS-4, SYS-5, SYS-6, SYS-13, SYS-14)
+
+## Reading ADRs
+
+### Option 1: Read YAML directly
+```bash
+cat adrs/logical/ADR-L-0001-*.yaml
+```
+
+### Option 2: Read rendered markdown
+```bash
+cat adrs/rendered/ADR-L-0001.md
+```
+
+### Option 3: Query via RSS
+```bash
+npm run rss:search "RECON decisions"
+```
+
+## Updating ADRs
+
+1. Edit YAML file directly
+2. Validate: `python -m adr_kit.validator adrs/logical/ADR-L-0001.yaml`
+3. Regenerate manifest: `python -m adr_kit.generators.manifest_generator adrs/`
+4. Regenerate views: `python -m adr_kit.generators.views.markdown adrs/`
+
+## Migration History
+
+**Original E-ADRs:** Archived in `documentation/e-adr-archived/`  
+**Migration tool:** [adr-architecture-kit](https://github.com/egallmann/adr-architecture-kit)  
+**Migration date:** 2026-03-08
+
+See [MIGRATION.md](MIGRATION.md) for detailed migration process and rationale.
+
+## Why ADR Kit?
+
+1. **Machine-verifiable**: JSON Schema + Pydantic validation
+2. **AI-readable**: Deterministic structure for LLM consumption
+3. **Graph-integrated**: RECON extracts ADRs into semantic graph
+4. **STE-compliant**: Follows System of Thought Engineering principles
+5. **Discoverable**: Manifest enables fast queries (SYS-14: Index Currency)
+
+## References
+
+- [ADR Kit Documentation](https://github.com/egallmann/adr-architecture-kit)
+- [STE Architecture Specification](../spec/ste-spec/)
+- [Migration Guide](MIGRATION.md)