From 9715ae991248626acdcb8c1fe36dc732402a4327 Mon Sep 17 00:00:00 2001
From: rsimpson2 <rsimpson2@me.com>
Date: Fri, 3 Apr 2026 22:04:27 -0400
Subject: [PATCH 1/4] feat(telemetry): implement storage layer (Phase 1)

Add StorageBackend interface with append(), query(), count() methods.
Implement MemoryStorageBackend (in-process array, ephemeral) and
FileStorageBackend (JSONL append-only, lazy dir creation, graceful
handling of missing files and corrupted lines).

30 storage tests covering shared contract (both backends) plus
backend-specific behavior (persistence, JSONL format, nested dirs).

Closes tasks 1.1-1.4 in telemetry ROADMAP.
---
 HANDOFF.md                                    |  89 ++++++
 .../.openspec.yaml                            |   2 +
 .../2026-04-04-telemetry-phase-1/README.md    |   3 +
 .../2026-04-04-telemetry-phase-1/design.md    |  59 ++++
 .../2026-04-04-telemetry-phase-1/proposal.md  |  30 ++
 .../specs/file-storage/spec.md                |  65 +++++
 .../specs/memory-storage/spec.md              |  37 +++
 .../specs/storage-interface/spec.md           |  58 ++++
 .../2026-04-04-telemetry-phase-1/tasks.md     |  26 ++
 openspec/specs/file-storage/spec.md           |  71 +++++
 openspec/specs/memory-storage/spec.md         |  43 +++
 openspec/specs/storage-interface/spec.md      |  64 +++++
 packages/telemetry/ROADMAP.md                 |   6 +-
 packages/telemetry/src/index.ts               |   4 +
 .../src/storage/FileStorageBackend.ts         |  62 ++++
 .../src/storage/MemoryStorageBackend.ts       |  28 ++
 .../telemetry/src/storage/StorageBackend.ts   |   7 +
 packages/telemetry/tests/storage.test.ts      | 270 ++++++++++++++++++
 18 files changed, 921 insertions(+), 3 deletions(-)
 create mode 100644 HANDOFF.md
 create mode 100644 openspec/changes/archive/2026-04-04-telemetry-phase-1/.openspec.yaml
 create mode 100644 openspec/changes/archive/2026-04-04-telemetry-phase-1/README.md
 create mode 100644 openspec/changes/archive/2026-04-04-telemetry-phase-1/design.md
 create mode 100644 openspec/changes/archive/2026-04-04-telemetry-phase-1/proposal.md
 create mode 100644 openspec/changes/archive/2026-04-04-telemetry-phase-1/specs/file-storage/spec.md
 create mode 100644 openspec/changes/archive/2026-04-04-telemetry-phase-1/specs/memory-storage/spec.md
 create mode 100644 openspec/changes/archive/2026-04-04-telemetry-phase-1/specs/storage-interface/spec.md
 create mode 100644 openspec/changes/archive/2026-04-04-telemetry-phase-1/tasks.md
 create mode 100644 openspec/specs/file-storage/spec.md
 create mode 100644 openspec/specs/memory-storage/spec.md
 create mode 100644 openspec/specs/storage-interface/spec.md
 create mode 100644 packages/telemetry/src/storage/FileStorageBackend.ts
 create mode 100644 packages/telemetry/src/storage/MemoryStorageBackend.ts
 create mode 100644 packages/telemetry/src/storage/StorageBackend.ts
 create mode 100644 packages/telemetry/tests/storage.test.ts

diff --git a/HANDOFF.md b/HANDOFF.md
new file mode 100644
index 0000000..25e9530
--- /dev/null
+++ b/HANDOFF.md
@@ -0,0 +1,89 @@
+# Session Handoff
+
+Persistent context bridge for autonomous ROADMAP execution across sessions. Each session reads this file at startup and updates it after completing a phase.
+
+---
+
+## Current State
+
+| Field                    | Value                       |
+| ------------------------ | --------------------------- |
+| **Active Wave**          | Wave 1: Core Infrastructure |
+| **Active Package**       | telemetry                   |
+| **Last Completed Phase** | (none)                      |
+| **Last Session**         | **DATE**                    |
+| **ROADMAP Status**       | Starting                    |
+
+---
+
+## Completed Work
+
+| Wave       | Package | Phase | Title |
+| ---------- | ------- | ----- | ----- |
+| (none yet) |         |       |       |
+
+---
+
+## Key Decisions (ADR Summary)
+
+_Decisions will be documented here as phases are completed._
+
+---
+
+## Project Patterns
+
+Established patterns -- follow these in all packages:
+
+- **Module format**: ESM (`"type": "module"` in all packages)
+- **Imports**: Use `.js` extension in relative imports
+- **Types**: Co-locate in `types.ts` per module, export from `index.ts`
+- **Tests**: Place in `tests/` directory at package root, named `*.test.ts`
+- **Quality gates**: `npx nx affected -t build,test,lint`
+
+---
+
+## Known Issues & Gotchas
+
+_To be documented as issues are encountered._
+
+---
+
+## Lessons Learned
+
+_To be documented as the project progresses._
+
+---
+
+## Next Phase Context
+
+### Target
+
+Wave 1: @open-forge/telemetry Phase 1 (Storage Layer)
+
+### Goal
+
+Implement pluggable storage backends (memory + file-based) for telemetry events.
+
+### Critical Context
+
+- Telemetry types already defined in packages/telemetry/src/types.ts
+- Storage must be append-only (NF-010) and zero-config (NF-030)
+- File-based JSONL is the default backend
+
+---
+
+## Session Resumption Instructions
+
+1. Read this file: cat HANDOFF.md
+2. Check root status: bash scripts/forge-helper.sh status
+3. Check package status: bash scripts/forge-helper.sh status --package telemetry
+4. Resume work on the next phase
+5. After completion: update this file
+
+---
+
+## Changelog
+
+| Date       | Wave | Package | Phase | Notes              |
+| ---------- | ---- | ------- | ----- | ------------------ |
+| 2026-04-03 | --   | --      | --    | Created HANDOFF.md |
diff --git a/openspec/changes/archive/2026-04-04-telemetry-phase-1/.openspec.yaml b/openspec/changes/archive/2026-04-04-telemetry-phase-1/.openspec.yaml
new file mode 100644
index 0000000..c54c137
--- /dev/null
+++ b/openspec/changes/archive/2026-04-04-telemetry-phase-1/.openspec.yaml
@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-04-04
diff --git a/openspec/changes/archive/2026-04-04-telemetry-phase-1/README.md b/openspec/changes/archive/2026-04-04-telemetry-phase-1/README.md
new file mode 100644
index 0000000..b6c1666
--- /dev/null
+++ b/openspec/changes/archive/2026-04-04-telemetry-phase-1/README.md
@@ -0,0 +1,3 @@
+# telemetry-phase-1
+
+telemetry Phase 1: Storage Layer
diff --git a/openspec/changes/archive/2026-04-04-telemetry-phase-1/design.md b/openspec/changes/archive/2026-04-04-telemetry-phase-1/design.md
new file mode 100644
index 0000000..ff5e1e0
--- /dev/null
+++ b/openspec/changes/archive/2026-04-04-telemetry-phase-1/design.md
@@ -0,0 +1,59 @@
+## Context
+
+The `@open-forge/telemetry` package currently exports only TypeScript types (Phase 0). The storage layer is the first real implementation — it provides the persistence mechanism that `emit()` and `query()` (Phase 2) will use. The existing `PipelineEvent` and `EventFilter` types in `src/types.ts` define the data model.
+
+Constraint: Zero required runtime dependencies for core functionality (per package ROADMAP).
+
+## Goals / Non-Goals
+
+**Goals:**
+
+- Define a `StorageBackend` interface that decouples telemetry logic from persistence
+- Ship two concrete backends: in-memory (for tests/lightweight) and file-based JSONL (for production default)
+- All backends satisfy the same contract and are interchangeable
+- File backend works zero-config with only a path
+
+**Non-Goals:**
+
+- SQLite or database backends (deferred per ROADMAP)
+- Concurrent write safety across processes (single-writer assumption for v1)
+- Streaming/pagination for large result sets (can be added later)
+- Hot-swapping backends at runtime
+
+## Decisions
+
+### 1. StorageBackend as a standalone interface (not extending Telemetry)
+
+**Decision**: `StorageBackend` is a separate interface with `append()`, `query()`, `count()` — it does NOT extend or overlap with the `Telemetry` interface.
+
+**Rationale**: `Telemetry.emit()` will do validation and enrichment before calling `StorageBackend.append()`. Keeping them separate enforces single responsibility. The `Telemetry` implementation (Phase 2) composes a `StorageBackend`.
+
+**Alternative considered**: Having `Telemetry` directly implement storage. Rejected — couples business logic to I/O.
+
+### 2. JSONL for file storage format
+
+**Decision**: One JSON object per line, append-only.
+
+**Rationale**: Simple, human-readable, no corruption from partial writes (each line is independent), streamable, and requires no dependencies. Alternatives like SQLite or binary formats add complexity for marginal gains at this scale.
+
+### 3. File storage creates directories on first write, not on construction
+
+**Decision**: The `FileStorageBackend` constructor stores the path. Directory/file creation happens on first `append()`.
+
+**Rationale**: Avoids side effects during construction. `query()` on a non-existent file returns empty — no error.
+
+### 4. Query filtering uses in-process filtering
+
+**Decision**: Both backends load/scan events and filter in-process using `EventFilter` fields.
+
+**Rationale**: Simplicity. At expected telemetry volumes (hundreds to low thousands of events per pipeline), in-process filtering is fast enough. Indexing can be added in a future phase if needed.
+
+## Risks / Trade-offs
+
+- **[Large file performance]** → File backend reads the entire file for queries. Mitigation: acceptable for v1 volumes; SQLite backend is in the deferred items list.
+- **[No concurrent writes]** → Single-writer assumption. Mitigation: pipeline is single-threaded; document the limitation.
+- **[JSONL corruption on crash]** → Partial line write possible if process crashes mid-append. Mitigation: each line is independent; partial lines are skipped on read.
+
+## Open Questions
+
+None — scope is well-defined by the ROADMAP and requirements doc.
diff --git a/openspec/changes/archive/2026-04-04-telemetry-phase-1/proposal.md b/openspec/changes/archive/2026-04-04-telemetry-phase-1/proposal.md
new file mode 100644
index 0000000..8136e8d
--- /dev/null
+++ b/openspec/changes/archive/2026-04-04-telemetry-phase-1/proposal.md
@@ -0,0 +1,30 @@
+## Why
+
+The telemetry package currently exports only type definitions (Phase 0). Every downstream consumer — the pipeline orchestrator, constraint evaluator, and evaluations integration — needs real storage backends that can persist and query pipeline events. Without a storage layer, telemetry cannot function. This is the critical path: Wave 1 in the unified ROADMAP, blocking all subsequent waves.
+
+## What Changes
+
+- New `StorageBackend` interface defining the contract for all storage implementations (`append`, `query`, `count`)
+- In-memory storage backend for testing and lightweight/ephemeral use cases
+- File-based JSONL storage backend as the default zero-config production backend (append-only, no external dependencies)
+- All backends are pluggable — consumers choose at `createTelemetry()` time (Phase 4)
+
+## Capabilities
+
+### New Capabilities
+
+- `storage-interface`: Defines the `StorageBackend` contract — `append()`, `query()`, `count()` — that all storage implementations must satisfy
+- `memory-storage`: In-memory `StorageBackend` implementation for testing and lightweight use
+- `file-storage`: JSONL append-only file `StorageBackend` implementation as the default zero-config backend
+
+### Modified Capabilities
+
+<!-- No existing capabilities are being modified — this is all new implementation -->
+
+## Impact
+
+- **New files**: `src/storage/interface.ts`, `src/storage/memory.ts`, `src/storage/file.ts`, `tests/storage.test.ts`
+- **Modified files**: `src/index.ts` (export storage implementations)
+- **APIs**: New `StorageBackend` interface and two concrete implementations
+- **Dependencies**: Zero runtime dependencies (Node.js `fs` and `path` for file backend only)
+- **Downstream**: Unblocks Phase 2 (Telemetry Core) which needs storage to implement `emit()` and `query()`
diff --git a/openspec/changes/archive/2026-04-04-telemetry-phase-1/specs/file-storage/spec.md b/openspec/changes/archive/2026-04-04-telemetry-phase-1/specs/file-storage/spec.md
new file mode 100644
index 0000000..43d0069
--- /dev/null
+++ b/openspec/changes/archive/2026-04-04-telemetry-phase-1/specs/file-storage/spec.md
@@ -0,0 +1,65 @@
+## ADDED Requirements
+
+### Requirement: File storage implements StorageBackend
+
+The `FileStorageBackend` class SHALL implement the `StorageBackend` interface, persisting events as JSONL (one JSON object per line) in an append-only file.
+
+#### Scenario: Create file storage with path
+
+- **WHEN** a `FileStorageBackend` is instantiated with a file path
+- **THEN** it SHALL create the file (and parent directories) if they do not exist
+
+### Requirement: File storage append writes JSONL
+
+The `FileStorageBackend.append()` method SHALL serialize the event as JSON and append it as a single line to the storage file.
+
+#### Scenario: Append writes one line per event
+
+- **WHEN** three events are appended
+- **THEN** the file SHALL contain exactly three lines, each being valid JSON
+
+#### Scenario: Append is atomic per event
+
+- **WHEN** `append()` is called
+- **THEN** each event SHALL be written as a complete line (no partial writes visible to readers)
+
+### Requirement: File storage query reads and filters JSONL
+
+The `FileStorageBackend.query()` method SHALL read the JSONL file, parse each line, and filter by the provided `EventFilter`.
+
+#### Scenario: Query filters persisted events
+
+- **WHEN** events are appended and then queried with a filter
+- **THEN** only matching events SHALL be returned
+
+### Requirement: File storage persists across instances
+
+Events stored by `FileStorageBackend` SHALL be readable by a new instance pointing to the same file.
+
+#### Scenario: Data survives instance recreation
+
+- **WHEN** events are appended, the instance is discarded, and a new instance is created with the same path
+- **THEN** the new instance SHALL return the previously stored events via `query()`
+
+### Requirement: File storage count avoids full deserialization
+
+The `FileStorageBackend.count()` method SHALL count matching events efficiently without requiring all events to be held in memory simultaneously.
+
+#### Scenario: Count returns correct number
+
+- **WHEN** events are appended and `count()` is called with a matching filter
+- **THEN** the correct count SHALL be returned
+
+### Requirement: File storage handles empty or missing file
+
+The `FileStorageBackend` SHALL gracefully handle cases where the file does not yet exist or is empty.
+
+#### Scenario: Query on non-existent file
+
+- **WHEN** `query()` is called before any events are appended (file does not exist)
+- **THEN** an empty array SHALL be returned
+
+#### Scenario: Count on empty file
+
+- **WHEN** `count()` is called on an empty file
+- **THEN** zero SHALL be returned
diff --git a/openspec/changes/archive/2026-04-04-telemetry-phase-1/specs/memory-storage/spec.md b/openspec/changes/archive/2026-04-04-telemetry-phase-1/specs/memory-storage/spec.md
new file mode 100644
index 0000000..534f471
--- /dev/null
+++ b/openspec/changes/archive/2026-04-04-telemetry-phase-1/specs/memory-storage/spec.md
@@ -0,0 +1,37 @@
+## ADDED Requirements
+
+### Requirement: In-memory storage implements StorageBackend
+
+The `MemoryStorageBackend` class SHALL implement the `StorageBackend` interface, storing all events in an in-memory array.
+
+#### Scenario: Create in-memory storage
+
+- **WHEN** a `MemoryStorageBackend` is instantiated
+- **THEN** it SHALL be ready for use with zero configuration
+
+### Requirement: In-memory storage append is synchronous-fast
+
+The `MemoryStorageBackend.append()` method SHALL resolve immediately after pushing the event to the internal array.
+
+#### Scenario: Append resolves without delay
+
+- **WHEN** `append()` is called
+- **THEN** the promise SHALL resolve within 1ms under normal conditions
+
+### Requirement: In-memory storage query filters correctly
+
+The `MemoryStorageBackend.query()` method SHALL filter the internal array by all provided `EventFilter` fields.
+
+#### Scenario: Query with combined filters
+
+- **WHEN** multiple events exist for different pipelines and stages
+- **THEN** `query()` with combined filters SHALL return only matching events
+
+### Requirement: In-memory storage is ephemeral
+
+Events stored in `MemoryStorageBackend` SHALL not persist beyond the lifetime of the instance.
+
+#### Scenario: Data lost on new instance
+
+- **WHEN** a `MemoryStorageBackend` is created, events are appended, and a new instance is created
+- **THEN** the new instance SHALL have zero events
diff --git a/openspec/changes/archive/2026-04-04-telemetry-phase-1/specs/storage-interface/spec.md b/openspec/changes/archive/2026-04-04-telemetry-phase-1/specs/storage-interface/spec.md
new file mode 100644
index 0000000..b0f39d7
--- /dev/null
+++ b/openspec/changes/archive/2026-04-04-telemetry-phase-1/specs/storage-interface/spec.md
@@ -0,0 +1,58 @@
+## ADDED Requirements
+
+### Requirement: StorageBackend interface defines append operation
+
+The `StorageBackend` interface SHALL define an `append(event: PipelineEvent): Promise<void>` method that persists a single pipeline event to the storage backend.
+
+#### Scenario: Append a valid event
+
+- **WHEN** `append()` is called with a valid `PipelineEvent`
+- **THEN** the event SHALL be persisted and retrievable via `query()`
+
+#### Scenario: Append preserves event data
+
+- **WHEN** an event is appended and then queried back
+- **THEN** all fields of the returned event SHALL match the original event exactly
+
+### Requirement: StorageBackend interface defines query operation
+
+The `StorageBackend` interface SHALL define a `query(filter: EventFilter): Promise<PipelineEvent[]>` method that retrieves events matching the given filter criteria.
+
+#### Scenario: Query by pipelineId
+
+- **WHEN** `query()` is called with an `EventFilter` containing only `pipelineId`
+- **THEN** all events matching that `pipelineId` SHALL be returned
+
+#### Scenario: Query by pipelineId and stage
+
+- **WHEN** `query()` is called with an `EventFilter` containing `pipelineId` and `stage`
+- **THEN** only events matching both `pipelineId` and `stage` SHALL be returned
+
+#### Scenario: Query by pipelineId and action
+
+- **WHEN** `query()` is called with an `EventFilter` containing `pipelineId` and `action`
+- **THEN** only events matching both `pipelineId` and `action` SHALL be returned
+
+#### Scenario: Query by time range
+
+- **WHEN** `query()` is called with an `EventFilter` containing `from` and/or `to` timestamps
+- **THEN** only events within the specified time range SHALL be returned
+
+#### Scenario: Query returns empty for no matches
+
+- **WHEN** `query()` is called with a filter that matches no events
+- **THEN** an empty array SHALL be returned
+
+### Requirement: StorageBackend interface defines count operation
+
+The `StorageBackend` interface SHALL define a `count(filter: EventFilter): Promise<number>` method that returns the number of events matching the given filter without loading them all into memory.
+
+#### Scenario: Count matches query results
+
+- **WHEN** `count()` is called with the same filter as `query()`
+- **THEN** the returned number SHALL equal the length of the array returned by `query()` with the same filter
+
+#### Scenario: Count returns zero for no matches
+
+- **WHEN** `count()` is called with a filter that matches no events
+- **THEN** zero SHALL be returned
diff --git a/openspec/changes/archive/2026-04-04-telemetry-phase-1/tasks.md b/openspec/changes/archive/2026-04-04-telemetry-phase-1/tasks.md
new file mode 100644
index 0000000..c42aaed
--- /dev/null
+++ b/openspec/changes/archive/2026-04-04-telemetry-phase-1/tasks.md
@@ -0,0 +1,26 @@
+## 1. Storage Interface
+
+- [ ] 1.1 Define `StorageBackend` interface in `src/storage/interface.ts` with `append()`, `query()`, `count()` methods
+- [ ] 1.2 Export `StorageBackend` from `src/index.ts`
+
+## 2. In-Memory Storage
+
+- [ ] 2.1 Implement `MemoryStorageBackend` class in `src/storage/memory.ts`
+- [ ] 2.2 Implement `append()` — push event to internal array
+- [ ] 2.3 Implement `query()` — filter internal array by EventFilter fields (pipelineId, stage, action, from, to)
+- [ ] 2.4 Implement `count()` — return filtered count without extra allocation
+
+## 3. File-Based Storage
+
+- [ ] 3.1 Implement `FileStorageBackend` class in `src/storage/file.ts`
+- [ ] 3.2 Implement `append()` — serialize event as JSON, append line to file, create dirs on first write
+- [ ] 3.3 Implement `query()` — read JSONL file line-by-line, parse, filter by EventFilter
+- [ ] 3.4 Implement `count()` — count matching lines without holding all in memory
+- [ ] 3.5 Handle missing/empty file gracefully (return empty array / zero)
+
+## 4. Tests
+
+- [ ] 4.1 Write shared storage contract tests that both backends must pass
+- [ ] 4.2 Write memory-specific tests (ephemeral behavior)
+- [ ] 4.3 Write file-specific tests (persistence across instances, JSONL format, missing file handling)
+- [ ] 4.4 Verify all tests pass and quality gates clear
diff --git a/openspec/specs/file-storage/spec.md b/openspec/specs/file-storage/spec.md
new file mode 100644
index 0000000..6916d95
--- /dev/null
+++ b/openspec/specs/file-storage/spec.md
@@ -0,0 +1,71 @@
+# file-storage Specification
+
+## Purpose
+
+TBD - created by archiving change telemetry-phase-1. Update Purpose after archive.
+
+## Requirements
+
+### Requirement: File storage implements StorageBackend
+
+The `FileStorageBackend` class SHALL implement the `StorageBackend` interface, persisting events as JSONL (one JSON object per line) in an append-only file.
+
+#### Scenario: Create file storage with path
+
+- **WHEN** a `FileStorageBackend` is instantiated with a file path
+- **THEN** it SHALL create the file (and parent directories) if they do not exist
+
+### Requirement: File storage append writes JSONL
+
+The `FileStorageBackend.append()` method SHALL serialize the event as JSON and append it as a single line to the storage file.
+
+#### Scenario: Append writes one line per event
+
+- **WHEN** three events are appended
+- **THEN** the file SHALL contain exactly three lines, each being valid JSON
+
+#### Scenario: Append is atomic per event
+
+- **WHEN** `append()` is called
+- **THEN** each event SHALL be written as a complete line (no partial writes visible to readers)
+
+### Requirement: File storage query reads and filters JSONL
+
+The `FileStorageBackend.query()` method SHALL read the JSONL file, parse each line, and filter by the provided `EventFilter`.
+
+#### Scenario: Query filters persisted events
+
+- **WHEN** events are appended and then queried with a filter
+- **THEN** only matching events SHALL be returned
+
+### Requirement: File storage persists across instances
+
+Events stored by `FileStorageBackend` SHALL be readable by a new instance pointing to the same file.
+
+#### Scenario: Data survives instance recreation
+
+- **WHEN** events are appended, the instance is discarded, and a new instance is created with the same path
+- **THEN** the new instance SHALL return the previously stored events via `query()`
+
+### Requirement: File storage count avoids full deserialization
+
+The `FileStorageBackend.count()` method SHALL count matching events efficiently without requiring all events to be held in memory simultaneously.
+
+#### Scenario: Count returns correct number
+
+- **WHEN** events are appended and `count()` is called with a matching filter
+- **THEN** the correct count SHALL be returned
+
+### Requirement: File storage handles empty or missing file
+
+The `FileStorageBackend` SHALL gracefully handle cases where the file does not yet exist or is empty.
+
+#### Scenario: Query on non-existent file
+
+- **WHEN** `query()` is called before any events are appended (file does not exist)
+- **THEN** an empty array SHALL be returned
+
+#### Scenario: Count on empty file
+
+- **WHEN** `count()` is called on an empty file
+- **THEN** zero SHALL be returned
diff --git a/openspec/specs/memory-storage/spec.md b/openspec/specs/memory-storage/spec.md
new file mode 100644
index 0000000..336fa5c
--- /dev/null
+++ b/openspec/specs/memory-storage/spec.md
@@ -0,0 +1,43 @@
+# memory-storage Specification
+
+## Purpose
+
+TBD - created by archiving change telemetry-phase-1. Update Purpose after archive.
+
+## Requirements
+
+### Requirement: In-memory storage implements StorageBackend
+
+The `MemoryStorageBackend` class SHALL implement the `StorageBackend` interface, storing all events in an in-memory array.
+
+#### Scenario: Create in-memory storage
+
+- **WHEN** a `MemoryStorageBackend` is instantiated
+- **THEN** it SHALL be ready for use with zero configuration
+
+### Requirement: In-memory storage append is synchronous-fast
+
+The `MemoryStorageBackend.append()` method SHALL resolve immediately after pushing the event to the internal array.
+
+#### Scenario: Append resolves without delay
+
+- **WHEN** `append()` is called
+- **THEN** the promise SHALL resolve within 1ms under normal conditions
+
+### Requirement: In-memory storage query filters correctly
+
+The `MemoryStorageBackend.query()` method SHALL filter the internal array by all provided `EventFilter` fields.
+
+#### Scenario: Query with combined filters
+
+- **WHEN** multiple events exist for different pipelines and stages
+- **THEN** `query()` with combined filters SHALL return only matching events
+
+### Requirement: In-memory storage is ephemeral
+
+Events stored in `MemoryStorageBackend` SHALL not persist beyond the lifetime of the instance.
+
+#### Scenario: Data lost on new instance
+
+- **WHEN** a `MemoryStorageBackend` is created, events are appended, and a new instance is created
+- **THEN** the new instance SHALL have zero events
diff --git a/openspec/specs/storage-interface/spec.md b/openspec/specs/storage-interface/spec.md
new file mode 100644
index 0000000..ab18110
--- /dev/null
+++ b/openspec/specs/storage-interface/spec.md
@@ -0,0 +1,64 @@
+# storage-interface Specification
+
+## Purpose
+
+TBD - created by archiving change telemetry-phase-1. Update Purpose after archive.
+
+## Requirements
+
+### Requirement: StorageBackend interface defines append operation
+
+The `StorageBackend` interface SHALL define an `append(event: PipelineEvent): Promise<void>` method that persists a single pipeline event to the storage backend.
+
+#### Scenario: Append a valid event
+
+- **WHEN** `append()` is called with a valid `PipelineEvent`
+- **THEN** the event SHALL be persisted and retrievable via `query()`
+
+#### Scenario: Append preserves event data
+
+- **WHEN** an event is appended and then queried back
+- **THEN** all fields of the returned event SHALL match the original event exactly
+
+### Requirement: StorageBackend interface defines query operation
+
+The `StorageBackend` interface SHALL define a `query(filter: EventFilter): Promise<PipelineEvent[]>` method that retrieves events matching the given filter criteria.
+
+#### Scenario: Query by pipelineId
+
+- **WHEN** `query()` is called with an `EventFilter` containing only `pipelineId`
+- **THEN** all events matching that `pipelineId` SHALL be returned
+
+#### Scenario: Query by pipelineId and stage
+
+- **WHEN** `query()` is called with an `EventFilter` containing `pipelineId` and `stage`
+- **THEN** only events matching both `pipelineId` and `stage` SHALL be returned
+
+#### Scenario: Query by pipelineId and action
+
+- **WHEN** `query()` is called with an `EventFilter` containing `pipelineId` and `action`
+- **THEN** only events matching both `pipelineId` and `action` SHALL be returned
+
+#### Scenario: Query by time range
+
+- **WHEN** `query()` is called with an `EventFilter` containing `from` and/or `to` timestamps
+- **THEN** only events within the specified time range SHALL be returned
+
+#### Scenario: Query returns empty for no matches
+
+- **WHEN** `query()` is called with a filter that matches no events
+- **THEN** an empty array SHALL be returned
+
+### Requirement: StorageBackend interface defines count operation
+
+The `StorageBackend` interface SHALL define a `count(filter: EventFilter): Promise<number>` method that returns the number of events matching the given filter without loading them all into memory.
+
+#### Scenario: Count matches query results
+
+- **WHEN** `count()` is called with the same filter as `query()`
+- **THEN** the returned number SHALL equal the length of the array returned by `query()` with the same filter
+
+#### Scenario: Count returns zero for no matches
+
+- **WHEN** `count()` is called with a filter that matches no events
+- **THEN** zero SHALL be returned
diff --git a/packages/telemetry/ROADMAP.md b/packages/telemetry/ROADMAP.md
index 29225ae..2c4d67e 100644
--- a/packages/telemetry/ROADMAP.md
+++ b/packages/telemetry/ROADMAP.md
@@ -30,9 +30,9 @@ This roadmap breaks down the [telemetry REQUIREMENTS](../../docs/open-forge-tele
 
 ### Tasks
 
-- [ ] 1.1 Define storage interface [deps: 0.2] [deliverable: `src/storage/interface.ts` — StorageBackend with append(), query(), count()]
-- [ ] 1.2 Implement in-memory storage [deps: 1.1] [deliverable: `src/storage/memory.ts` — for testing and lightweight use]
-- [ ] 1.3 Implement file-based storage [deps: 1.1] [deliverable: `src/storage/file.ts` — JSONL append-only file, default zero-config backend]
+- [ ] 1.1 Define storage interface [deps: 0.2] [deliverable: `src/storage/StorageBackend.ts` — StorageBackend with append(), query(), count()]
+- [ ] 1.2 Implement in-memory storage [deps: 1.1] [deliverable: `src/storage/MemoryStorageBackend.ts` — for testing and lightweight use]
+- [ ] 1.3 Implement file-based storage [deps: 1.1] [deliverable: `src/storage/FileStorageBackend.ts` — JSONL append-only file, default zero-config backend]
 - [ ] 1.4 Write storage tests [deps: 1.2, 1.3] [deliverable: `tests/storage.test.ts`]
 
 **Parallel Groups**:
diff --git a/packages/telemetry/src/index.ts b/packages/telemetry/src/index.ts
index 0ba6d69..cc9da6a 100644
--- a/packages/telemetry/src/index.ts
+++ b/packages/telemetry/src/index.ts
@@ -12,3 +12,7 @@ export type {
   TelemetryConfig,
   OpenForgeTelemetry,
 } from './types.js';
+
+export type { StorageBackend } from './storage/StorageBackend.js';
+export { MemoryStorageBackend } from './storage/MemoryStorageBackend.js';
+export { FileStorageBackend } from './storage/FileStorageBackend.js';
diff --git a/packages/telemetry/src/storage/FileStorageBackend.ts b/packages/telemetry/src/storage/FileStorageBackend.ts
new file mode 100644
index 0000000..19c317a
--- /dev/null
+++ b/packages/telemetry/src/storage/FileStorageBackend.ts
@@ -0,0 +1,62 @@
+import { appendFile, readFile, mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+import type { PipelineEvent, EventFilter } from '../types.js';
+import type { StorageBackend } from './StorageBackend.js';
+
+export class FileStorageBackend implements StorageBackend {
+  private readonly filePath: string;
+
+  constructor(filePath: string) {
+    this.filePath = filePath;
+  }
+
+  async append(event: PipelineEvent): Promise<void> {
+    await mkdir(dirname(this.filePath), { recursive: true });
+    await appendFile(this.filePath, JSON.stringify(event) + '\n', 'utf-8');
+  }
+
+  async query(filter: EventFilter): Promise<PipelineEvent[]> {
+    const events = await this.readAll();
+    return events.filter((e) => matchesFilter(e, filter));
+  }
+
+  async count(filter: EventFilter): Promise<number> {
+    const events = await this.readAll();
+    return events.filter((e) => matchesFilter(e, filter)).length;
+  }
+
+  private async readAll(): Promise<PipelineEvent[]> {
+    let content: string;
+    try {
+      content = await readFile(this.filePath, 'utf-8');
+    } catch (err: unknown) {
+      if (isNodeError(err) && err.code === 'ENOENT') return [];
+      throw err;
+    }
+
+    return content
+      .split('\n')
+      .filter((line) => line.trim() !== '')
+      .flatMap((line) => {
+        try {
+          return [JSON.parse(line) as PipelineEvent];
+        } catch {
+          return [];
+        }
+      });
+  }
+}
+
+function matchesFilter(event: PipelineEvent, filter: EventFilter): boolean {
+  if (event.pipelineId !== filter.pipelineId) return false;
+  if (filter.stage !== undefined && event.stage !== filter.stage) return false;
+  if (filter.action !== undefined && event.action !== filter.action)
+    return false;
+  if (filter.from !== undefined && event.timestamp < filter.from) return false;
+  if (filter.to !== undefined && event.timestamp > filter.to) return false;
+  return true;
+}
+
+function isNodeError(err: unknown): err is NodeJS.ErrnoException {
+  return err instanceof Error && 'code' in err;
+}
diff --git a/packages/telemetry/src/storage/MemoryStorageBackend.ts b/packages/telemetry/src/storage/MemoryStorageBackend.ts
new file mode 100644
index 0000000..f961f93
--- /dev/null
+++ b/packages/telemetry/src/storage/MemoryStorageBackend.ts
@@ -0,0 +1,28 @@
+import type { PipelineEvent, EventFilter } from '../types.js';
+import type { StorageBackend } from './StorageBackend.js';
+
+export class MemoryStorageBackend implements StorageBackend {
+  private readonly events: PipelineEvent[] = [];
+
+  async append(event: PipelineEvent): Promise<void> {
+    this.events.push(event);
+  }
+
+  async query(filter: EventFilter): Promise<PipelineEvent[]> {
+    return this.events.filter((e) => matchesFilter(e, filter));
+  }
+
+  async count(filter: EventFilter): Promise<number> {
+    return this.events.filter((e) => matchesFilter(e, filter)).length;
+  }
+}
+
+function matchesFilter(event: PipelineEvent, filter: EventFilter): boolean {
+  if (event.pipelineId !== filter.pipelineId) return false;
+  if (filter.stage !== undefined && event.stage !== filter.stage) return false;
+  if (filter.action !== undefined && event.action !== filter.action)
+    return false;
+  if (filter.from !== undefined && event.timestamp < filter.from) return false;
+  if (filter.to !== undefined && event.timestamp > filter.to) return false;
+  return true;
+}
diff --git a/packages/telemetry/src/storage/StorageBackend.ts b/packages/telemetry/src/storage/StorageBackend.ts
new file mode 100644
index 0000000..a508432
--- /dev/null
+++ b/packages/telemetry/src/storage/StorageBackend.ts
@@ -0,0 +1,7 @@
+import type { PipelineEvent, EventFilter } from '../types.js';
+
+export interface StorageBackend {
+  append(event: PipelineEvent): Promise<void>;
+  query(filter: EventFilter): Promise<PipelineEvent[]>;
+  count(filter: EventFilter): Promise<number>;
+}
diff --git a/packages/telemetry/tests/storage.test.ts b/packages/telemetry/tests/storage.test.ts
new file mode 100644
index 0000000..937edd7
--- /dev/null
+++ b/packages/telemetry/tests/storage.test.ts
@@ -0,0 +1,270 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { mkdtemp, rm, readFile } from 'node:fs/promises';
+import type { PipelineEvent } from '../src/types.js';
+import type { StorageBackend } from '../src/storage/StorageBackend.js';
+import { MemoryStorageBackend } from '../src/storage/MemoryStorageBackend.js';
+import { FileStorageBackend } from '../src/storage/FileStorageBackend.js';
+
+function makeEvent(overrides: Partial<PipelineEvent> = {}): PipelineEvent {
+  return {
+    timestamp: new Date().toISOString(),
+    pipelineId: 'pipeline-1',
+    phase: 1,
+    stage: 'plan',
+    action: 'start',
+    ...overrides,
+  };
+}
+
+function describeStorageContract(
+  name: string,
+  factory: () => Promise<StorageBackend>
+) {
+  describe(`${name} — StorageBackend contract`, () => {
+    let storage: StorageBackend;
+
+    beforeEach(async () => {
+      storage = await factory();
+    });
+
+    it('should return empty array when no events exist', async () => {
+      const result = await storage.query({ pipelineId: 'nonexistent' });
+      expect(result).toEqual([]);
+    });
+
+    it('should return zero count when no events exist', async () => {
+      const count = await storage.count({ pipelineId: 'nonexistent' });
+      expect(count).toBe(0);
+    });
+
+    it('should append and query a single event', async () => {
+      const event = makeEvent();
+      await storage.append(event);
+
+      const result = await storage.query({ pipelineId: 'pipeline-1' });
+      expect(result).toHaveLength(1);
+      expect(result[0]).toEqual(event);
+    });
+
+    it('should preserve all event fields through append and query', async () => {
+      const event = makeEvent({
+        durationMs: 1500,
+        tokenUsage: { prompt: 100, completion: 200 },
+        agentId: 'agent-1',
+        model: 'gpt-4',
+        filesModified: ['src/foo.ts'],
+        filesCreated: ['src/bar.ts'],
+        error: 'some error',
+        metadata: { key: 'value' },
+      });
+
+      await storage.append(event);
+      const result = await storage.query({ pipelineId: 'pipeline-1' });
+      expect(result[0]).toEqual(event);
+    });
+
+    it('should filter by pipelineId', async () => {
+      await storage.append(makeEvent({ pipelineId: 'p1' }));
+      await storage.append(makeEvent({ pipelineId: 'p2' }));
+      await storage.append(makeEvent({ pipelineId: 'p1' }));
+
+      const result = await storage.query({ pipelineId: 'p1' });
+      expect(result).toHaveLength(2);
+      expect(result.every((e) => e.pipelineId === 'p1')).toBe(true);
+    });
+
+    it('should filter by pipelineId and stage', async () => {
+      await storage.append(makeEvent({ stage: 'plan' }));
+      await storage.append(makeEvent({ stage: 'test' }));
+      await storage.append(makeEvent({ stage: 'plan' }));
+
+      const result = await storage.query({
+        pipelineId: 'pipeline-1',
+        stage: 'plan',
+      });
+      expect(result).toHaveLength(2);
+    });
+
+    it('should filter by pipelineId and action', async () => {
+      await storage.append(makeEvent({ action: 'start' }));
+      await storage.append(makeEvent({ action: 'complete' }));
+      await storage.append(makeEvent({ action: 'fail' }));
+
+      const result = await storage.query({
+        pipelineId: 'pipeline-1',
+        action: 'complete',
+      });
+      expect(result).toHaveLength(1);
+      expect(result[0]).toBeDefined();
+      expect(result[0]?.action).toBe('complete');
+    });
+
+    it('should filter by time range (from)', async () => {
+      await storage.append(
+        makeEvent({ timestamp: '2024-01-01T00:00:00.000Z' })
+      );
+      await storage.append(
+        makeEvent({ timestamp: '2024-06-01T00:00:00.000Z' })
+      );
+      await storage.append(
+        makeEvent({ timestamp: '2024-12-01T00:00:00.000Z' })
+      );
+
+      const result = await storage.query({
+        pipelineId: 'pipeline-1',
+        from: '2024-06-01T00:00:00.000Z',
+      });
+      expect(result).toHaveLength(2);
+    });
+
+    it('should filter by time range (to)', async () => {
+      await storage.append(
+        makeEvent({ timestamp: '2024-01-01T00:00:00.000Z' })
+      );
+      await storage.append(
+        makeEvent({ timestamp: '2024-06-01T00:00:00.000Z' })
+      );
+      await storage.append(
+        makeEvent({ timestamp: '2024-12-01T00:00:00.000Z' })
+      );
+
+      const result = await storage.query({
+        pipelineId: 'pipeline-1',
+        to: '2024-06-01T00:00:00.000Z',
+      });
+      expect(result).toHaveLength(2);
+    });
+
+    it('should filter by time range (from and to)', async () => {
+      await storage.append(
+        makeEvent({ timestamp: '2024-01-01T00:00:00.000Z' })
+      );
+      await storage.append(
+        makeEvent({ timestamp: '2024-06-01T00:00:00.000Z' })
+      );
+      await storage.append(
+        makeEvent({ timestamp: '2024-12-01T00:00:00.000Z' })
+      );
+
+      const result = await storage.query({
+        pipelineId: 'pipeline-1',
+        from: '2024-03-01T00:00:00.000Z',
+        to: '2024-09-01T00:00:00.000Z',
+      });
+      expect(result).toHaveLength(1);
+    });
+
+    it('should count matching events', async () => {
+      await storage.append(makeEvent({ pipelineId: 'p1' }));
+      await storage.append(makeEvent({ pipelineId: 'p2' }));
+      await storage.append(makeEvent({ pipelineId: 'p1' }));
+
+      expect(await storage.count({ pipelineId: 'p1' })).toBe(2);
+      expect(await storage.count({ pipelineId: 'p2' })).toBe(1);
+      expect(await storage.count({ pipelineId: 'p3' })).toBe(0);
+    });
+
+    it('should count with combined filters', async () => {
+      await storage.append(makeEvent({ stage: 'plan', action: 'start' }));
+      await storage.append(makeEvent({ stage: 'plan', action: 'complete' }));
+      await storage.append(makeEvent({ stage: 'test', action: 'start' }));
+
+      expect(
+        await storage.count({
+          pipelineId: 'pipeline-1',
+          stage: 'plan',
+          action: 'start',
+        })
+      ).toBe(1);
+    });
+  });
+}
+
+describeStorageContract(
+  'MemoryStorageBackend',
+  async () => new MemoryStorageBackend()
+);
+
+describe('FileStorageBackend', () => {
+  let tempDir: string;
+
+  beforeEach(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), 'telemetry-test-'));
+  });
+
+  afterEach(async () => {
+    await rm(tempDir, { recursive: true, force: true });
+  });
+
+  describeStorageContract(
+    'FileStorageBackend',
+    async () => new FileStorageBackend(join(tempDir, 'events.jsonl'))
+  );
+
+  it('should persist events across instances', async () => {
+    const filePath = join(tempDir, 'persist.jsonl');
+    const storage1 = new FileStorageBackend(filePath);
+
+    await storage1.append(makeEvent({ pipelineId: 'persist-test' }));
+    await storage1.append(makeEvent({ pipelineId: 'persist-test' }));
+
+    const storage2 = new FileStorageBackend(filePath);
+    const result = await storage2.query({ pipelineId: 'persist-test' });
+    expect(result).toHaveLength(2);
+  });
+
+  it('should write one JSON line per event', async () => {
+    const filePath = join(tempDir, 'lines.jsonl');
+    const storage = new FileStorageBackend(filePath);
+
+    await storage.append(makeEvent());
+    await storage.append(makeEvent());
+    await storage.append(makeEvent());
+
+    const content = await readFile(filePath, 'utf-8');
+    const lines = content.trim().split('\n');
+    expect(lines).toHaveLength(3);
+
+    for (const line of lines) {
+      expect(() => JSON.parse(line)).not.toThrow();
+    }
+  });
+
+  it('should handle query on non-existent file', async () => {
+    const storage = new FileStorageBackend(
+      join(tempDir, 'nonexistent', 'events.jsonl')
+    );
+    const result = await storage.query({ pipelineId: 'any' });
+    expect(result).toEqual([]);
+  });
+
+  it('should handle count on non-existent file', async () => {
+    const storage = new FileStorageBackend(
+      join(tempDir, 'nonexistent', 'events.jsonl')
+    );
+    const count = await storage.count({ pipelineId: 'any' });
+    expect(count).toBe(0);
+  });
+
+  it('should create parent directories on first append', async () => {
+    const filePath = join(tempDir, 'nested', 'deep', 'events.jsonl');
+    const storage = new FileStorageBackend(filePath);
+
+    await storage.append(makeEvent());
+    const result = await storage.query({ pipelineId: 'pipeline-1' });
+    expect(result).toHaveLength(1);
+  });
+});
+
+describe('MemoryStorageBackend — ephemeral behavior', () => {
+  it('should not share state between instances', async () => {
+    const storage1 = new MemoryStorageBackend();
+    await storage1.append(makeEvent());
+
+    const storage2 = new MemoryStorageBackend();
+    const result = await storage2.query({ pipelineId: 'pipeline-1' });
+    expect(result).toEqual([]);
+  });
+});

From 41953f865e04a07ce6dfc6f816ebb4da72e23920 Mon Sep 17 00:00:00 2001
From: rsimpson2 <rsimpson2@me.com>
Date: Fri, 3 Apr 2026 22:04:53 -0400
Subject: [PATCH 2/4] chore: update handoff after telemetry Phase 1

---
 HANDOFF.md | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

diff --git a/HANDOFF.md b/HANDOFF.md
index 25e9530..f7ed550 100644
--- a/HANDOFF.md
+++ b/HANDOFF.md
@@ -10,9 +10,9 @@ Persistent context bridge for autonomous ROADMAP execution across sessions. Each
 | ------------------------ | --------------------------- |
 | **Active Wave**          | Wave 1: Core Infrastructure |
 | **Active Package**       | telemetry                   |
-| **Last Completed Phase** | (none)                      |
-| **Last Session**         | **DATE**                    |
-| **ROADMAP Status**       | Starting                    |
+| **Last Completed Phase** | telemetry phase 1           |
+| **Last Session**         | 2026-04-03                  |
+| **ROADMAP Status**       | Phase 1 complete            |
 
 ---
 
@@ -84,6 +84,7 @@ Implement pluggable storage backends (memory + file-based) for telemetry events.
 
 ## Changelog
 
-| Date       | Wave | Package | Phase | Notes              |
-| ---------- | ---- | ------- | ----- | ------------------ |
-| 2026-04-03 | --   | --      | --    | Created HANDOFF.md |
+| Date       | Wave | Package   | Phase | Notes                      |
+| ---------- | ---- | --------- | ----- | -------------------------- |
+| 2026-04-03 | --   | --        | --    | Created HANDOFF.md         |
+| 2026-04-03 | --   | telemetry | 1     | Storage Layer -- 4/4 tasks |

From c650e68e364df610ef71996d9a85ce56c6bac848 Mon Sep 17 00:00:00 2001
From: rsimpson2 <rsimpson2@me.com>
Date: Sat, 4 Apr 2026 08:22:10 -0400
Subject: [PATCH 3/4] refactor(telemetry): address PR #20 review feedback

- Extract shared matchesFilter utility from both storage backends
- Add dirCreated flag to FileStorageBackend to skip redundant mkdir
- Fix afterEach import in storage tests (explicit vitest import)
- Correct filenames and task items in OpenSpec change artifacts
- Fill Purpose fields in all three main specs
- Weaken file-storage count() claim to match implementation
- Fix constructor scenario to reflect lazy dir creation
- Update HANDOFF.md with completed work and next phase context
---
 HANDOFF.md                                    | 43 ++++++++++++-------
 .../2026-04-04-telemetry-phase-1/proposal.md  |  2 +-
 .../2026-04-04-telemetry-phase-1/tasks.md     | 36 +++++++++-------
 openspec/specs/file-storage/spec.md           |  9 ++--
 openspec/specs/memory-storage/spec.md         |  2 +-
 openspec/specs/storage-interface/spec.md      |  2 +-
 .../src/storage/FileStorageBackend.ts         | 17 +++-----
 .../src/storage/MemoryStorageBackend.ts       | 11 +----
 .../telemetry/src/storage/matchesFilter.ts    | 14 ++++++
 packages/telemetry/tests/storage.test.ts      |  2 +-
 10 files changed, 77 insertions(+), 61 deletions(-)
 create mode 100644 packages/telemetry/src/storage/matchesFilter.ts

diff --git a/HANDOFF.md b/HANDOFF.md
index f7ed550..e288723 100644
--- a/HANDOFF.md
+++ b/HANDOFF.md
@@ -11,22 +11,26 @@ Persistent context bridge for autonomous ROADMAP execution across sessions. Each
 | **Active Wave**          | Wave 1: Core Infrastructure |
 | **Active Package**       | telemetry                   |
 | **Last Completed Phase** | telemetry phase 1           |
-| **Last Session**         | 2026-04-03                  |
+| **Last Session**         | 2026-04-04                  |
 | **ROADMAP Status**       | Phase 1 complete            |
 
 ---
 
 ## Completed Work
 
-| Wave       | Package | Phase | Title |
-| ---------- | ------- | ----- | ----- |
-| (none yet) |         |       |       |
+| Wave   | Package   | Phase   | Title                           |
+| ------ | --------- | ------- | ------------------------------- |
+| Wave 1 | telemetry | Phase 0 | Foundation (types, scaffolding) |
+| Wave 1 | telemetry | Phase 1 | Storage Layer (Memory + File)   |
 
 ---
 
 ## Key Decisions (ADR Summary)
 
-_Decisions will be documented here as phases are completed._
+- **Storage backends are pluggable**: `StorageBackend` interface with `append()`, `query()`, `count()`. Consumers choose backend at `createTelemetry()` time (Phase 4).
+- **JSONL file format**: Default zero-config backend uses newline-delimited JSON. Append-only, no external dependencies.
+- **`matchesFilter` is shared**: Extracted to `src/storage/matchesFilter.ts` to avoid duplication across backends.
+- **Lazy directory creation**: `FileStorageBackend` creates directories on first `append()`, not at construction time.
 
 ---
 
@@ -39,18 +43,22 @@ Established patterns -- follow these in all packages:
 - **Types**: Co-locate in `types.ts` per module, export from `index.ts`
 - **Tests**: Place in `tests/` directory at package root, named `*.test.ts`
 - **Quality gates**: `npx nx affected -t build,test,lint`
+- **Shared utilities**: Extract duplicated logic to standalone files named after the export (`filename-match-export` rule)
+- **Empty catch pattern**: Use `flatMap` with `try/catch` returning `[]` for skip-on-error — no logging needed
 
 ---
 
 ## Known Issues & Gotchas
 
-_To be documented as issues are encountered._
+- `count()` in both backends loads all events into memory before counting. Acceptable for Phase 1; optimize in a future phase if needed.
 
 ---
 
 ## Lessons Learned
 
-_To be documented as the project progresses._
+- The `llm-core/filename-match-export` lint rule requires files with a single export to be named after that export.
+- The comments hook flags all new comments/docstrings — only add when absolutely necessary.
+- `afterEach` must be explicitly imported from vitest (not relied upon as a global).
 
 ---
 
@@ -58,17 +66,19 @@ _To be documented as the project progresses._
 
 ### Target
 
-Wave 1: @open-forge/telemetry Phase 1 (Storage Layer)
+Wave 1: @open-forge/telemetry Phase 2 (Telemetry Core)
 
 ### Goal
 
-Implement pluggable storage backends (memory + file-based) for telemetry events.
+Implement event emission and querying — the `Telemetry` interface: `emit()`, `query()`, `getPipelineSummary()`.
 
 ### Critical Context
 
-- Telemetry types already defined in packages/telemetry/src/types.ts
-- Storage must be append-only (NF-010) and zero-config (NF-030)
-- File-based JSONL is the default backend
+- Storage backends are complete and tested (33 tests passing)
+- Types already defined in `packages/telemetry/src/types.ts` (including `Telemetry`, `PipelineSummary`)
+- Phase 2 deliverable: `src/telemetry.ts` + `tests/telemetry.test.ts`
+- Sequential dependency: 2.1 (`emit`) → 2.2 (`query`) → 2.3 (`getPipelineSummary`) → 2.4 (tests)
+- Requirements covered: F-001, F-002, F-003, F-004, F-005, F-006, F-007, F-013
 
 ---
 
@@ -84,7 +94,8 @@ Implement pluggable storage backends (memory + file-based) for telemetry events.
 
 ## Changelog
 
-| Date       | Wave | Package   | Phase | Notes                      |
-| ---------- | ---- | --------- | ----- | -------------------------- |
-| 2026-04-03 | --   | --        | --    | Created HANDOFF.md         |
-| 2026-04-03 | --   | telemetry | 1     | Storage Layer -- 4/4 tasks |
+| Date       | Wave   | Package   | Phase | Notes                                    |
+| ---------- | ------ | --------- | ----- | ---------------------------------------- |
+| 2026-04-03 | --     | --        | --    | Created HANDOFF.md                       |
+| 2026-04-03 | Wave 1 | telemetry | 1     | Storage Layer -- 4/4 tasks               |
+| 2026-04-04 | Wave 1 | telemetry | 1     | PR review fixes, matchesFilter extracted |
diff --git a/openspec/changes/archive/2026-04-04-telemetry-phase-1/proposal.md b/openspec/changes/archive/2026-04-04-telemetry-phase-1/proposal.md
index 8136e8d..7cea150 100644
--- a/openspec/changes/archive/2026-04-04-telemetry-phase-1/proposal.md
+++ b/openspec/changes/archive/2026-04-04-telemetry-phase-1/proposal.md
@@ -23,7 +23,7 @@ The telemetry package currently exports only type definitions (Phase 0). Every d
 
 ## Impact
 
-- **New files**: `src/storage/interface.ts`, `src/storage/memory.ts`, `src/storage/file.ts`, `tests/storage.test.ts`
+- **New files**: `src/storage/StorageBackend.ts`, `src/storage/MemoryStorageBackend.ts`, `src/storage/FileStorageBackend.ts`, `src/storage/matchesFilter.ts`, `tests/storage.test.ts`
 - **Modified files**: `src/index.ts` (export storage implementations)
 - **APIs**: New `StorageBackend` interface and two concrete implementations
 - **Dependencies**: Zero runtime dependencies (Node.js `fs` and `path` for file backend only)
diff --git a/openspec/changes/archive/2026-04-04-telemetry-phase-1/tasks.md b/openspec/changes/archive/2026-04-04-telemetry-phase-1/tasks.md
index c42aaed..4170f14 100644
--- a/openspec/changes/archive/2026-04-04-telemetry-phase-1/tasks.md
+++ b/openspec/changes/archive/2026-04-04-telemetry-phase-1/tasks.md
@@ -1,26 +1,30 @@
 ## 1. Storage Interface
 
-- [ ] 1.1 Define `StorageBackend` interface in `src/storage/interface.ts` with `append()`, `query()`, `count()` methods
-- [ ] 1.2 Export `StorageBackend` from `src/index.ts`
+- [x] 1.1 Define `StorageBackend` interface in `src/storage/StorageBackend.ts` with `append()`, `query()`, `count()` methods
+- [x] 1.2 Export `StorageBackend` from `src/index.ts`
 
 ## 2. In-Memory Storage
 
-- [ ] 2.1 Implement `MemoryStorageBackend` class in `src/storage/memory.ts`
-- [ ] 2.2 Implement `append()` — push event to internal array
-- [ ] 2.3 Implement `query()` — filter internal array by EventFilter fields (pipelineId, stage, action, from, to)
-- [ ] 2.4 Implement `count()` — return filtered count without extra allocation
+- [x] 2.1 Implement `MemoryStorageBackend` class in `src/storage/MemoryStorageBackend.ts`
+- [x] 2.2 Implement `append()` — push event to internal array
+- [x] 2.3 Implement `query()` — filter internal array by EventFilter fields (pipelineId, stage, action, from, to)
+- [x] 2.4 Implement `count()` — return filtered count
 
 ## 3. File-Based Storage
 
-- [ ] 3.1 Implement `FileStorageBackend` class in `src/storage/file.ts`
-- [ ] 3.2 Implement `append()` — serialize event as JSON, append line to file, create dirs on first write
-- [ ] 3.3 Implement `query()` — read JSONL file line-by-line, parse, filter by EventFilter
-- [ ] 3.4 Implement `count()` — count matching lines without holding all in memory
-- [ ] 3.5 Handle missing/empty file gracefully (return empty array / zero)
+- [x] 3.1 Implement `FileStorageBackend` class in `src/storage/FileStorageBackend.ts`
+- [x] 3.2 Implement `append()` — serialize event as JSON, append line to file, create dirs on first write
+- [x] 3.3 Implement `query()` — read JSONL file, parse, filter by EventFilter
+- [x] 3.4 Implement `count()` — count matching events via query
+- [x] 3.5 Handle missing/empty file gracefully (return empty array / zero)
 
-## 4. Tests
+## 4. Shared Utilities
 
-- [ ] 4.1 Write shared storage contract tests that both backends must pass
-- [ ] 4.2 Write memory-specific tests (ephemeral behavior)
-- [ ] 4.3 Write file-specific tests (persistence across instances, JSONL format, missing file handling)
-- [ ] 4.4 Verify all tests pass and quality gates clear
+- [x] 4.1 Extract `matchesFilter` to `src/storage/matchesFilter.ts` — shared across both backends
+
+## 5. Tests
+
+- [x] 5.1 Write shared storage contract tests that both backends must pass
+- [x] 5.2 Write memory-specific tests (ephemeral behavior)
+- [x] 5.3 Write file-specific tests (persistence across instances, JSONL format, missing file handling)
+- [x] 5.4 Verify all tests pass and quality gates clear
diff --git a/openspec/specs/file-storage/spec.md b/openspec/specs/file-storage/spec.md
index 6916d95..7f914f7 100644
--- a/openspec/specs/file-storage/spec.md
+++ b/openspec/specs/file-storage/spec.md
@@ -2,7 +2,7 @@
 
 ## Purpose
 
-TBD - created by archiving change telemetry-phase-1. Update Purpose after archive.
+JSONL append-only file implementation of the `StorageBackend` interface. Serves as the default zero-config production backend — persists pipeline events as newline-delimited JSON with no external dependencies.
 
 ## Requirements
 
@@ -13,7 +13,8 @@ The `FileStorageBackend` class SHALL implement the `StorageBackend` interface, p
 #### Scenario: Create file storage with path
 
 - **WHEN** a `FileStorageBackend` is instantiated with a file path
-- **THEN** it SHALL create the file (and parent directories) if they do not exist
+- **THEN** it SHALL store the path for later use
+- **AND** it SHALL NOT create the file or parent directories until the first `append()` call
 
 ### Requirement: File storage append writes JSONL
 
@@ -47,9 +48,9 @@ Events stored by `FileStorageBackend` SHALL be readable by a new instance pointi
 - **WHEN** events are appended, the instance is discarded, and a new instance is created with the same path
 - **THEN** the new instance SHALL return the previously stored events via `query()`
 
-### Requirement: File storage count avoids full deserialization
+### Requirement: File storage count returns correct results
 
-The `FileStorageBackend.count()` method SHALL count matching events efficiently without requiring all events to be held in memory simultaneously.
+The `FileStorageBackend.count()` method SHALL return the correct count of matching events. It SHOULD avoid full deserialization where practical, but MAY load all events for simplicity in early implementations.
 
 #### Scenario: Count returns correct number
 
diff --git a/openspec/specs/memory-storage/spec.md b/openspec/specs/memory-storage/spec.md
index 336fa5c..e7db57e 100644
--- a/openspec/specs/memory-storage/spec.md
+++ b/openspec/specs/memory-storage/spec.md
@@ -2,7 +2,7 @@
 
 ## Purpose
 
-TBD - created by archiving change telemetry-phase-1. Update Purpose after archive.
+In-memory implementation of the `StorageBackend` interface for testing and lightweight ephemeral use cases. Events are stored in a plain array and do not persist beyond the lifetime of the instance.
 
 ## Requirements
 
diff --git a/openspec/specs/storage-interface/spec.md b/openspec/specs/storage-interface/spec.md
index ab18110..1120847 100644
--- a/openspec/specs/storage-interface/spec.md
+++ b/openspec/specs/storage-interface/spec.md
@@ -2,7 +2,7 @@
 
 ## Purpose
 
-TBD - created by archiving change telemetry-phase-1. Update Purpose after archive.
+Defines the `StorageBackend` contract (`append`, `query`, `count`) that all telemetry storage implementations must satisfy. Decouples telemetry business logic from persistence — consumers choose a concrete backend at composition time.
 
 ## Requirements
 
diff --git a/packages/telemetry/src/storage/FileStorageBackend.ts b/packages/telemetry/src/storage/FileStorageBackend.ts
index 19c317a..bf35670 100644
--- a/packages/telemetry/src/storage/FileStorageBackend.ts
+++ b/packages/telemetry/src/storage/FileStorageBackend.ts
@@ -2,16 +2,21 @@ import { appendFile, readFile, mkdir } from 'node:fs/promises';
 import { dirname } from 'node:path';
 import type { PipelineEvent, EventFilter } from '../types.js';
 import type { StorageBackend } from './StorageBackend.js';
+import { matchesFilter } from './matchesFilter.js';
 
 export class FileStorageBackend implements StorageBackend {
   private readonly filePath: string;
+  private dirCreated = false;
 
   constructor(filePath: string) {
     this.filePath = filePath;
   }
 
   async append(event: PipelineEvent): Promise<void> {
-    await mkdir(dirname(this.filePath), { recursive: true });
+    if (!this.dirCreated) {
+      await mkdir(dirname(this.filePath), { recursive: true });
+      this.dirCreated = true;
+    }
     await appendFile(this.filePath, JSON.stringify(event) + '\n', 'utf-8');
   }
 
@@ -47,16 +52,6 @@ export class FileStorageBackend implements StorageBackend {
   }
 }
 
-function matchesFilter(event: PipelineEvent, filter: EventFilter): boolean {
-  if (event.pipelineId !== filter.pipelineId) return false;
-  if (filter.stage !== undefined && event.stage !== filter.stage) return false;
-  if (filter.action !== undefined && event.action !== filter.action)
-    return false;
-  if (filter.from !== undefined && event.timestamp < filter.from) return false;
-  if (filter.to !== undefined && event.timestamp > filter.to) return false;
-  return true;
-}
-
 function isNodeError(err: unknown): err is NodeJS.ErrnoException {
   return err instanceof Error && 'code' in err;
 }
diff --git a/packages/telemetry/src/storage/MemoryStorageBackend.ts b/packages/telemetry/src/storage/MemoryStorageBackend.ts
index f961f93..232bd3a 100644
--- a/packages/telemetry/src/storage/MemoryStorageBackend.ts
+++ b/packages/telemetry/src/storage/MemoryStorageBackend.ts
@@ -1,5 +1,6 @@
 import type { PipelineEvent, EventFilter } from '../types.js';
 import type { StorageBackend } from './StorageBackend.js';
+import { matchesFilter } from './matchesFilter.js';
 
 export class MemoryStorageBackend implements StorageBackend {
   private readonly events: PipelineEvent[] = [];
@@ -16,13 +17,3 @@ export class MemoryStorageBackend implements StorageBackend {
     return this.events.filter((e) => matchesFilter(e, filter)).length;
   }
 }
-
-function matchesFilter(event: PipelineEvent, filter: EventFilter): boolean {
-  if (event.pipelineId !== filter.pipelineId) return false;
-  if (filter.stage !== undefined && event.stage !== filter.stage) return false;
-  if (filter.action !== undefined && event.action !== filter.action)
-    return false;
-  if (filter.from !== undefined && event.timestamp < filter.from) return false;
-  if (filter.to !== undefined && event.timestamp > filter.to) return false;
-  return true;
-}
diff --git a/packages/telemetry/src/storage/matchesFilter.ts b/packages/telemetry/src/storage/matchesFilter.ts
new file mode 100644
index 0000000..49f01e9
--- /dev/null
+++ b/packages/telemetry/src/storage/matchesFilter.ts
@@ -0,0 +1,14 @@
+import type { PipelineEvent, EventFilter } from '../types.js';
+
+export function matchesFilter(
+  event: PipelineEvent,
+  filter: EventFilter
+): boolean {
+  if (event.pipelineId !== filter.pipelineId) return false;
+  if (filter.stage !== undefined && event.stage !== filter.stage) return false;
+  if (filter.action !== undefined && event.action !== filter.action)
+    return false;
+  if (filter.from !== undefined && event.timestamp < filter.from) return false;
+  if (filter.to !== undefined && event.timestamp > filter.to) return false;
+  return true;
+}
diff --git a/packages/telemetry/tests/storage.test.ts b/packages/telemetry/tests/storage.test.ts
index 937edd7..ac7b9f4 100644
--- a/packages/telemetry/tests/storage.test.ts
+++ b/packages/telemetry/tests/storage.test.ts
@@ -1,4 +1,4 @@
-import { describe, it, expect, beforeEach } from 'vitest';
+import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { mkdtemp, rm, readFile } from 'node:fs/promises';

From b16ecd701bc42fc6c5a3c7ea12292165ea6e62e0 Mon Sep 17 00:00:00 2001
From: rsimpson2 <rsimpson2@me.com>
Date: Sat, 4 Apr 2026 08:29:49 -0400
Subject: [PATCH 4/4] fix: add verify and sync steps before archive in
 forge-loop workflow

The forge-loop was missing /opsx-verify and /opsx-sync steps between
commit and archive, causing workflow violations. Also removed -y flag
from archive call so the built-in sync assessment isn't auto-skipped.

Deprecates packages/mcp/LOOP.md in favor of docs/LOOP.md.
---
 .claude/commands/forge-loop.md | 18 +++++++++++++-----
 docs/LOOP.md                   | 22 +++++++++++++++++-----
 packages/mcp/LOOP.md           |  2 ++
 3 files changed, 32 insertions(+), 10 deletions(-)

diff --git a/.claude/commands/forge-loop.md b/.claude/commands/forge-loop.md
index a6d47c8..6cd180d 100644
--- a/.claude/commands/forge-loop.md
+++ b/.claude/commands/forge-loop.md
@@ -188,15 +188,23 @@ Document in `PIPELINE-ISSUES.md` and continue to next step.
 bash scripts/forge-helper.sh phase-commit <phase> --package <pkg> "<title>"
 ```
 
-### 2h. Archive
+### 2h. Verify
+
+Run `/opsx-verify` against the change to confirm implementation matches artifacts (completeness, correctness, coherence). Fix any CRITICAL issues before proceeding.
+
+### 2i. Sync specs
+
+Run `/opsx-sync` against the change to merge delta specs into main specs. If no delta specs exist, this is a no-op.
+
+### 2j. Archive
 
 ```bash
-openspec archive "<change_name>" -y
+openspec archive "<change_name>"
 ```
 
-Warn but continue if archive fails.
+The archive command includes its own sync assessment at Step 4 — review and confirm. Warn but continue if archive fails.
 
-### 2i. Update handoff
+### 2k. Update handoff
 
 ```bash
 bash scripts/forge-helper.sh update-handoff <phase> "<title>" --package <pkg> <done> <total>
@@ -212,7 +220,7 @@ Append new key decisions to `HANDOFF.md`:
 - **Impact**: How it affects future phases
 ```
 
-### 2j. Show summary and loop
+### 2l. Show summary and loop
 
 ```bash
 bash scripts/forge-helper.sh status --package <pkg>
diff --git a/docs/LOOP.md b/docs/LOOP.md
index b4b76db..03c7d61 100644
--- a/docs/LOOP.md
+++ b/docs/LOOP.md
@@ -36,8 +36,10 @@ The agent works autonomously through pending phases. Interrupt at any time; rest
 │  7. Implement tasks, mark each done                       │
 │  8. forge-helper.sh check --package <pkg>                 │
 │  9. forge-helper.sh phase-commit <N> --package <pkg>      │
-│ 10. openspec archive "<pkg>-phase-N" -y                   │
-│ 11. Update HANDOFF.md                                     │
+│ 10. /opsx-verify (confirm implementation matches specs)   │
+│ 11. /opsx-sync (merge delta specs to main specs)          │
+│ 12. openspec archive "<pkg>-phase-N"                      │
+│ 13. Update HANDOFF.md                                     │
 │                                                           │
 │  Loop to next phase                                       │
 └──────────────────────────────────────────────────────────┘
@@ -140,13 +142,23 @@ If checks fail:
 bash scripts/forge-helper.sh phase-commit N --package <pkg> "<title>"
 ```
 
-### 8. Archive
+### 8. Verify
+
+Run `/opsx-verify` against the change to confirm implementation matches artifacts (completeness, correctness, coherence). Fix any CRITICAL issues before proceeding.
+
+### 9. Sync specs
+
+Run `/opsx-sync` against the change to merge delta specs into main specs. If no delta specs exist, this is a no-op.
+
+### 10. Archive
 
 ```bash
-openspec archive "$CHANGE" -y
+openspec archive "$CHANGE"
 ```
 
-### 9. Update handoff
+The archive command includes its own sync assessment — review and confirm.
+
+### 11. Update handoff
 
 ```bash
 bash scripts/forge-helper.sh update-handoff N "<title>" --package <pkg> <done> <total>
diff --git a/packages/mcp/LOOP.md b/packages/mcp/LOOP.md
index 0a05f1d..3bb469e 100644
--- a/packages/mcp/LOOP.md
+++ b/packages/mcp/LOOP.md
@@ -1,3 +1,5 @@
+> **DEPRECATED** — This file is specific to the MCP package's original loop setup. The canonical forge loop documentation lives at [`/docs/LOOP.md`](../../docs/LOOP.md) and the command at [`/.claude/commands/forge-loop.md`](../../.claude/commands/forge-loop.md).
+
 # Automation Loop
 
 The ROADMAP is completed by an **LLM agent** running inside OpenCode, not by a