murmur8 4.5.1 → 4.6.0

package/.blueprint/features/feature_pipeline-telemetry/FEATURE_SPEC.md

@@ -0,0 +1,297 @@
+---
+featureId: a3f8c2d1-7e54-4b09-8f16-23a1e5d94c72
+---
+
+# Feature Specification — Pipeline Telemetry
+
+## 1. Feature Intent
+
+**Why this feature exists.**
+
+- **Problem being addressed:** Teams using murmur8 have no visibility into pipeline usage across projects or over time at an aggregate level. Individual projects may have local history, but there is no mechanism to send structured execution data to a central observability endpoint for fleet-wide analysis, cost attribution, or quality tracking.
+- **User need:** Platform teams and administrators want to understand how murmur8 is being used — which features succeed or fail, how long stages take, and whether quality is improving. This is opt-in by configuration, not mandated.
+- **System purpose alignment:** Per SYSTEM_SPEC.md:Section 8 (Cross-Cutting Concerns:Observability), the system aims for observability. This feature extends that observability to an external, configurable telemetry layer without modifying the core pipeline flow.
+
+> This feature reinforces the system's observability goals and does not alter pipeline behaviour. It is completely silent when no endpoint is configured.
+
+---
+
+## 2. Scope
+
+### In Scope
+
+- Sending a structured JSON event payload via HTTP POST to a configurable telemetry endpoint at the end of each pipeline run
+- Reading endpoint URL and API key from `.env` file and real environment variables (env vars take precedence)
+- Non-blocking send: failures never interrupt the pipeline
+- Queuing failed sends to `.claude/telemetry-failed.json`; retrying queued sends at the start of the next pipeline run
+- Compressing artifact content (FEATURE_SPEC.md and story files) with zlib gzip + base64 before inclusion in payload
+- Generating a `runId` (UUID v4) at pipeline start for correlating events
+- Writing a `featureId` (UUID v4) into FEATURE_SPEC.md YAML frontmatter by Alex on first creation; stable across retries
+- New CLI command `murmur8 telemetry-config` to display current telemetry configuration
+- `init` command creating/appending a commented-out telemetry template to `.env` and ensuring `.env` is in `.gitignore`
+- Exporting telemetry functions from `src/index.js`
+- Storing `runId` in the history entry
+
+### Out of Scope
+
+- An opt-out flag (presence of URL = opt-in; absence = opt-out)
+- Real-time or streaming telemetry (end-of-run POST only)
+- Telemetry for non-pipeline CLI commands (e.g., `history`, `queue`)
+- Encryption of payload beyond HTTPS transport
+- Telemetry dashboard or receiver implementation
+- dotenv or any third-party `.env` parsing dependency (manual parsing only)
+
+---
+
+## 3. Actors Involved
+
+### Human User / Administrator
+
+- **Can do:** Configure telemetry endpoint and key via `.env`; view telemetry config via `murmur8 telemetry-config`; remove config to disable
+- **Cannot do:** Trigger telemetry manually; view the contents of failed send queue via CLI (file inspection only)
+
+### Pipeline Orchestrator (internal)
+
+- **Can do:** Generate `runId` at pipeline start; call telemetry send at pipeline end; enqueue failed sends; retry failed sends at start of next run
+- **Cannot do:** Block pipeline on telemetry failure; modify payload after send attempt
+
+### Alex Agent (internal)
+
+- **Can do:** Write `featureId` UUID into FEATURE_SPEC.md YAML frontmatter on first creation; preserve existing `featureId` on re-runs
+- **Cannot do:** Regenerate `featureId` if one already exists
+
+---
+
+## 4. Behaviour Overview
+
+### Happy-path behaviour
+
+1. User configures `MURMUR8_TELEMETRY_URL` (and optionally `MURMUR8_TELEMETRY_KEY`) in `.env` or as real environment variables
+2. At pipeline start (Step 5 of SKILL.md), orchestrator generates a `runId` UUID v4 and stores it in working context
+3. Alex writes a `featureId` UUID into FEATURE_SPEC.md YAML frontmatter (if not already present)
+4. Pipeline executes normally; timings, stage statuses, and feedback are collected as usual
+5. At pipeline end (Step 12 of SKILL.md), `src/telemetry.js` builds the payload, compresses artifacts, and POSTs to the configured URL
+6. On success, no user-visible output occurs (silent)
+7. On failure, the payload is appended to `.claude/telemetry-failed.json` silently
+
+### Key alternatives or branches
+
+- **No URL configured:** Telemetry module does nothing; pipeline continues as normal
+- **Send failure (network error, non-2xx response):** Payload written to failed queue; no pipeline interruption
+- **Retry at next run start:** Any entries in `.claude/telemetry-failed.json` are attempted before the new run proceeds; failures remain in queue
+- **`--no-feedback` flag used:** `feedback` block omitted from payload
+- **`featureId` already present in FEATURE_SPEC.md:** Alex preserves existing value; does not regenerate
+
+### User-visible outcomes
+
+- No output when telemetry is working correctly (fully silent)
+- `murmur8 telemetry-config` shows configured URL (masked key), retry queue depth
+
+---
+
+## 5. State & Lifecycle Interactions
+
+### States entered
+
+- **telemetry_pending:** `runId` generated at pipeline start; stored in working context
+- **telemetry_sent:** Payload successfully POSTed at pipeline end
+- **telemetry_queued:** Send failed; payload appended to `.claude/telemetry-failed.json`
+
+### States modified
+
+- `featureId` written into FEATURE_SPEC.md frontmatter (by Alex, on first run only)
+- History entry extended with `runId` field
+- `.claude/telemetry-failed.json` appended to on send failure; entries removed on successful retry
+
+### This feature is:
+
+- **State-creating:** Creates `runId` per run; may create `telemetry-failed.json`
+- **State-transitioning:** Moves failed payloads from queued → sent on retry
+- **Not state-constraining:** Does not block any pipeline operations
+
+---
+
+## 6. Rules & Decision Logic
+
+### Rule: Telemetry Activation
+
+- **Description:** Telemetry is active if and only if `MURMUR8_TELEMETRY_URL` is set (non-empty) in `.env` or real env
+- **Inputs:** Presence and value of `MURMUR8_TELEMETRY_URL`
+- **Outputs:** Active or inactive module
+- **Deterministic:** Yes
+
+### Rule: Environment Variable Precedence
+
+- **Description:** Real environment variables take precedence over `.env` file values for both `MURMUR8_TELEMETRY_URL` and `MURMUR8_TELEMETRY_KEY`
+- **Inputs:** `process.env` values, `.env` file parse result
+- **Outputs:** Resolved URL and key
+- **Deterministic:** Yes
+
+### Rule: runId Generation
+
+- **Description:** A new UUID v4 `runId` is generated at Step 5 of SKILL.md for every pipeline run, regardless of whether telemetry is active
+- **Inputs:** None (random UUID)
+- **Outputs:** UUID v4 string stored in working context and history entry
+- **Deterministic:** No (random)
+
+### Rule: featureId Stability
+
+- **Description:** `featureId` is written by Alex into FEATURE_SPEC.md frontmatter on first creation. If FEATURE_SPEC.md already contains a `featureId`, it must not be changed.
+- **Inputs:** Existing FEATURE_SPEC.md content
+- **Outputs:** Frontmatter with stable `featureId`
+- **Deterministic:** Yes (preserves existing); No for initial generation (random UUID)
+
+### Rule: Non-blocking Send
+
+- **Description:** The HTTP POST to the telemetry endpoint must not block or throw into the pipeline. Any network or HTTP error results in silent queue, not pipeline abort.
+- **Inputs:** HTTP response code, network errors
+- **Outputs:** Success (silent) or enqueue to failed queue (silent)
+- **Deterministic:** Yes
+
+### Rule: Failed Queue Retry
+
+- **Description:** At the start of each pipeline run (before Step 1 processing), any entries in `.claude/telemetry-failed.json` are attempted. Successfully sent entries are removed; failures remain.
+- **Inputs:** Contents of `.claude/telemetry-failed.json`
+- **Outputs:** Updated queue file (or file removed if empty)
+- **Deterministic:** Yes
+
+### Rule: Artifact Compression
+
+- **Description:** FEATURE_SPEC.md and any `story-*.md` files are gzip-compressed (zlib) and base64-encoded before inclusion in the `artifacts` block. Each file is keyed by its filename.
+- **Inputs:** File contents
+- **Outputs:** `{ "filename": "<base64-gzip>" }` per file
+- **Deterministic:** Yes (given same input)
+
+### Rule: Authorization Header
+
+- **Description:** If `MURMUR8_TELEMETRY_KEY` is set, it is sent as `Authorization: Bearer <key>` header. If not set, the header is omitted.
+- **Inputs:** Key value
+- **Outputs:** HTTP Authorization header presence
+- **Deterministic:** Yes
+
+---
+
+## 7. Dependencies
+
+### System components
+
+- `src/history.js` — Must pass `runId` to the history entry write
+- `SKILL.md` Step 5 — Must generate `runId`; Step 12 — Must call telemetry send
+- `src/init.js` — Must create/append `.env` template and update `.gitignore`
+- `bin/cli.js` — Must register `telemetry-config` command
+- `src/index.js` — Must export telemetry functions
+
+### External systems
+
+- Configurable HTTP/HTTPS endpoint (operator-supplied); must accept POST with JSON body
+- zlib (Node.js built-in) — for gzip compression
+- Node.js `crypto` module (built-in) — for UUID v4 generation
+- Node.js `https`/`http` modules (built-in) — for HTTP POST; no external HTTP library
+
+### Operational dependencies
+
+- `.env` file at project root (optional; telemetry inactive if absent or URL not set)
+- File system access to `.claude/` directory for failed queue
+- Network access to configured endpoint (no hard dependency — failures are tolerated)
+
+---
+
+## 8. Non-Functional Considerations
+
+### Performance sensitivity
+
+- Telemetry send is fire-and-forget (async, non-blocking); it must not add measurable latency to the user-visible pipeline completion
+- Artifact compression is performed in-process; acceptable for typical spec file sizes (<50 KB combined)
+
+### Audit/logging needs
+
+- The telemetry payload itself constitutes a structured audit record
+- `runId` links telemetry events to local history entries for cross-referencing
+- `featureId` provides stable identity across retries of the same feature
+
+### Error tolerance
+
+- Send failures must be fully silent to the user (no output, no pipeline interruption)
+- Failed queue must not grow unboundedly — implementations should consider a maximum retry depth (e.g., 50 entries), dropping oldest on overflow; exact limit is an implementation decision
+
+### Security implications
+
+- `MURMUR8_TELEMETRY_KEY` must never be logged or displayed in plaintext; `telemetry-config` command must mask the key (e.g., `sk-****1234`)
+- `.env` file must be added to `.gitignore` by the `init` command to prevent accidental credential commit
+- `gitEmail` and `repoUrl` are included in the identity block; operators must be aware these are transmitted to the configured endpoint
+- Payload transmitted over HTTPS (URL is operator-configured; framework does not enforce HTTPS but should warn if `http://` is used)
+
+---
+
+## 9. Assumptions & Open Questions
+
+### Assumptions
+
+- ASSUMPTION: Node.js built-in `zlib`, `crypto`, `https`/`http` modules are sufficient; no external dependencies needed
+- ASSUMPTION: `git config user.name`, `git config user.email`, and `git remote get-url origin` are available and executable in the pipeline environment
+- ASSUMPTION: Artifact files (FEATURE_SPEC.md, story files) are small enough that synchronous gzip compression is non-blocking in practice
+- ASSUMPTION: The telemetry endpoint is operator-managed; murmur8 does not validate the endpoint URL beyond basic format
+- ASSUMPTION: UUID v4 can be generated using `crypto.randomUUID()` (Node.js 15.6+; within Node.js 18+ requirement)
+
+### Open Questions
+
+- Should the failed queue have a configurable maximum depth, or a fixed cap (e.g., 50)?
+- Should `telemetry-config` provide a `--test` flag to send a synthetic ping to verify connectivity?
+- Should the `init` command emit a user-visible notice that `.env` was created (to aid discoverability)?
+
+---
+
+## 10. Impact on System Specification
+
+### Alignment assessment
+
+This feature **reinforces existing system assumptions** and introduces a minor extension:
+
+- Per SYSTEM_SPEC.md:Section 8 (Observability), the system already exposes queue status and completion summaries. This feature adds an optional external observability channel.
+- SYSTEM_SPEC.md:Section 3 (Out of Scope) excludes CI/CD integration, but telemetry to an operator endpoint is a distinct concern (usage analytics, not CI automation). No contradiction.
+- SYSTEM_SPEC.md:Section 9 (Non-Functional:Reliability) states the system must not be blocked by side-effects. This feature's non-blocking, silent-failure design directly upholds that invariant.
+
+### Minor extension to system spec warranted
+
+The following additions to SYSTEM_SPEC.md are flagged for consideration (not applied here):
+
+1. **Section 5 (Core Domain Concepts):** Add entry for `Run Identifier (runId)` — a UUID v4 generated per pipeline invocation for telemetry correlation and history linkage.
+2. **Section 5:** Add entry for `Feature Identifier (featureId)` — a UUID v4 written into FEATURE_SPEC.md frontmatter by Alex on first creation; stable across retries.
+3. **Section 8 (Cross-Cutting Concerns):** Add sub-section for external telemetry noting the opt-in model.
+
+These are **non-breaking extensions** flagged for Alex/human decision.
+
+---
+
+## 11. Handover to BA (Cass)
+
+### Story themes
+
+1. **Telemetry activation** — Configuring the endpoint and key; understanding opt-in model
+2. **runId and featureId generation** — Identifier lifecycle at pipeline start and spec creation
+3. **Payload construction and send** — Building and POSTing the event at pipeline end
+4. **Failed send queue** — Queuing failed sends and retrying at next run start
+5. **init integration** — `.env` template creation and `.gitignore` protection
+6. **telemetry-config command** — Viewing current configuration with masked key
+
+### Expected story boundaries
+
+- Activation/config story should be separate from the payload/send story
+- `featureId` (Alex behaviour) and `runId` (orchestrator behaviour) may be combined into one story or split by agent concern
+- Failed queue retry is a distinct story (edge case behaviour, important for reliability)
+- `init` changes are a small story but have a user-visible outcome (discoverability of the feature)
+
+### Areas needing careful story framing
+
+- The "completely silent when no endpoint configured" behaviour needs an explicit AC (absence of output is the expected outcome)
+- The precedence rule (real env vars override `.env`) needs a dedicated AC
+- The `featureId` preservation rule (no regeneration on re-run) needs a dedicated AC
+- Security: key masking in `telemetry-config` output needs explicit AC
+
+---
+
+## 12. Change Log (Feature-Level)
+
+| Date       | Change                                 | Reason                         | Raised By |
+|------------|----------------------------------------|--------------------------------|-----------|
+| 2026-05-19 | Initial feature specification created | New feature: telemetry layer   | Alex      |

package/.blueprint/features/feature_pipeline-telemetry/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,34 @@
+# Implementation Plan — pipeline-telemetry
+
+## Summary
+
+Create `src/telemetry.js` as the core module exporting all telemetry primitives (config loading, UUID generation, payload building, gzip compression, queue management, init helpers, and config formatting). Add `src/commands/telemetry-config.js` as a thin CLI wrapper, then wire the new module into `src/index.js`, `src/init.js`, and `bin/cli.js`. No external dependencies are required; Node.js built-ins (`crypto`, `zlib`, `https`, `fs`) cover all needs.
+
+## Files to Create / Modify
+
+| File | Action | Purpose |
+|------|--------|---------|
+| `src/telemetry.js` | **Create** | All exported telemetry functions |
+| `src/commands/telemetry-config.js` | **Create** | CLI command handler for `telemetry-config` |
+| `src/index.js` | **Modify** | Export telemetry functions |
+| `src/init.js` | **Modify** | Call `ensureDotenv` and `ensureGitignore` during init |
+| `bin/cli.js` | **No change needed** | Dynamic command loading already handles new commands |
+
+## Numbered Steps
+
+1. `src/telemetry.js` CREATE `loadConfig(dotenvPath)` — manual `.env` parse; env vars win; returns `{ url, key }` (null if absent) | Tests: T-TA-1 to T-TA-6
+2. `src/telemetry.js` ADD `generateRunId()` — returns `crypto.randomUUID()` | Tests: T-ID-1, T-ID-2, T-ID-5
+3. `src/telemetry.js` ADD `ensureFeatureId(specPath)` — reads file, extracts YAML frontmatter `featureId`; generates UUID v4 and prepends/updates frontmatter if absent | Tests: T-ID-3, T-ID-4, T-ID-5
+4. `src/telemetry.js` ADD `buildPayload(runData)` — assembles `{ runId, run: { featureId, slug, status, startedAt, completedAt, totalDurationMs, stages } }`; omits `feedback` key when value is falsy/empty; passes `artifacts` through unchanged | Tests: T-PS-1 to T-PS-4, T-PS-6
+5. `src/telemetry.js` ADD `compressArtifact(content)` — synchronous `zlib.gzipSync(content)` then `.toString('base64')` | Tests: T-PS-3, T-PS-5
+6. `src/telemetry.js` ADD `enqueueFailure(payload, queuePath)` — reads queue (or `[]` on missing/corrupt); appends payload; trims to last 50; writes JSON | Tests: T-FQ-1, T-FQ-6
+7. `src/telemetry.js` ADD `retryQueue(queuePath, sendFn)` — reads queue; calls `sendFn(payload)` for each entry; keeps entries where `sendFn` returns falsy; writes remaining (or `[]`) back to file | Tests: T-FQ-2 to T-FQ-5
+8. `src/telemetry.js` ADD `ensureDotenv(targetDir)` and `ensureGitignore(targetDir)` — create/append `.env` template (idempotent on `MURMUR8_TELEMETRY_URL` presence); add `.env` line to `.gitignore` if absent (create if needed) | Tests: T-II-1 to T-II-5
+9. `src/telemetry.js` ADD `formatTelemetryConfig(config, queuePath)` — returns string with URL, masked key (`****last4` or "not set"), active/inactive status, queue depth (reads file or 0) | Tests: T-TC-1 to T-TC-6
+10. `src/commands/telemetry-config.js` CREATE `run(args)` — loads config via `loadConfig`, reads queue path, calls `formatTelemetryConfig`, prints result; `src/index.js` ADD telemetry exports; `src/init.js` CALL `ensureDotenv`+`ensureGitignore` | Tests: T-TC-1 to T-TC-6, T-II-1 to T-II-5
+
+## Risks
+
+- `ensureFeatureId` must handle three frontmatter states: no frontmatter, frontmatter without `featureId`, and frontmatter with existing `featureId`. YAML is parsed with regex/string logic (no yaml dep); edge cases like multi-document or trailing dashes need careful handling.
+- `retryQueue` contract: `sendFn` returns truthy on success (synchronous). If the real `sendTelemetry` is async, callers must `await` and pass a resolved boolean — document this clearly in comments.
+- Queue overflow logic drops the **oldest** entries (index 0), keeping the newest. Verify slice direction: `queue.slice(-49)` then push gives correct oldest-dropped behaviour.

package/.blueprint/features/feature_pipeline-telemetry/handoff-alex.md

@@ -0,0 +1,21 @@
+## Handoff Summary
+**For:** Cass
+**Feature:** pipeline-telemetry
+
+### Key Decisions
+- Telemetry is opt-in by configuration: setting `MURMUR8_TELEMETRY_URL` activates it; absence = fully silent (no flag needed to disable)
+- Non-blocking by design: HTTP send failures enqueue to `.claude/telemetry-failed.json` silently; retry happens at next pipeline start — pipeline is never interrupted
+- Two stable identifiers: `runId` (UUID v4, per run, generated at Step 5) and `featureId` (UUID v4, per feature spec, written by Alex into frontmatter on first creation, never regenerated)
+- No external dependencies: uses Node.js built-ins only (`zlib`, `crypto`, `https`/`http`) — no dotenv, no HTTP client library
+- `.env` parsed manually with real env vars taking precedence; `init` command adds commented template and ensures `.gitignore` protection
+
+### Files Created
+- .blueprint/features/feature_pipeline-telemetry/FEATURE_SPEC.md
+
+### Open Questions
+- Should the failed-send queue have a configurable max depth or a fixed cap (e.g., 50 entries)?
+- Should `telemetry-config` offer a `--test` flag to ping the endpoint for connectivity verification?
+- Should `init` emit a visible notice that `.env` was created, to improve discoverability?
+
+### Critical Context
+This feature is infrastructure-level and cross-cutting: it touches SKILL.md (Step 5 for runId, Step 12 for send), `src/init.js` (`.env` + `.gitignore`), `src/history.js` (store runId), and introduces two new files (`src/telemetry.js`, `src/commands/telemetry-config.js`). The core principle is **silent by default** — no output when working, no errors surfaced to user on failure. Cass should write stories that make the "absence of output is correct behaviour" expectation explicit in acceptance criteria, as this is counter-intuitive but intentional. The `featureId` preservation rule (Alex must not regenerate an existing featureId) is a critical correctness invariant that needs a precise AC.

package/.blueprint/features/feature_pipeline-telemetry/handoff-cass.md

@@ -0,0 +1,25 @@
+## Handoff Summary
+**For:** Nigel
+**Feature:** pipeline-telemetry
+
+### Key Decisions
+- Telemetry is fully silent in both directions: no output when working correctly, no error output on failure — "absence of output is the correct behaviour" is an explicit AC in story-payload-send and story-failed-queue-retry
+- Six stories map directly to Alex's six story themes; each is independently testable
+- `featureId` preservation (AC-4 of story-identifiers) is a critical invariant: Alex must never regenerate a `featureId` that already exists in FEATURE_SPEC.md frontmatter
+- Environment variable precedence (process env overrides `.env`) is a dedicated AC in story-telemetry-activation (AC-3 and AC-6)
+- API key masking in `telemetry-config` output is an explicit security AC (story-telemetry-config-command AC-2)
+
+### Files Created
+- .blueprint/features/feature_pipeline-telemetry/story-telemetry-activation.md
+- .blueprint/features/feature_pipeline-telemetry/story-identifiers.md
+- .blueprint/features/feature_pipeline-telemetry/story-payload-send.md
+- .blueprint/features/feature_pipeline-telemetry/story-failed-queue-retry.md
+- .blueprint/features/feature_pipeline-telemetry/story-init-integration.md
+- .blueprint/features/feature_pipeline-telemetry/story-telemetry-config-command.md
+
+### Open Questions
+- Should the failed queue cap be configurable or hard-coded? (left as implementation-defined in story-failed-queue-retry AC-6)
+- Should `init` emit a visible notice when `.env` is created? (scoped out of story-init-integration per Alex's silent-by-default principle)
+
+### Critical Context
+This feature is infrastructure-level and cross-cutting. Tests must cover: (1) complete silence on success and failure paths, (2) the `featureId` no-regeneration invariant, (3) env var precedence over `.env`, (4) non-blocking behaviour (pipeline state unaffected by telemetry errors), and (5) key masking security property. All new code lives in `src/telemetry.js` and `src/commands/telemetry-config.js`; existing files touched are SKILL.md (Steps 5 and 12), `src/history.js`, `src/init.js`, `bin/cli.js`, and `src/index.js`.

package/.blueprint/features/feature_pipeline-telemetry/handoff-nigel.md

@@ -0,0 +1,20 @@
+## Handoff Summary
+**For:** Codey
+**Feature:** pipeline-telemetry
+
+### Key Decisions
+- Tests are self-contained: all helper functions (loadConfig, buildPayload, compressArtifact, etc.) are inlined in the test file — Codey must match these contracts exactly in src/telemetry.js
+- HTTP is never called in tests; send behaviour is validated via contract (headers, payload shape, silence on success)
+- Queue capped at 50 entries; overflow drops oldest
+- Queue cleanup on full success: write `[]` (not delete file)
+- All 7 story ambiguities resolved in test-spec.md assumptions
+
+### Files Created
+- test/artifacts/feature_pipeline-telemetry/test-spec.md
+- test/feature_pipeline-telemetry.test.js
+
+### Open Questions
+- None
+
+### Critical Context
+Tests define the contracts Codey must implement. Key exported functions expected from src/telemetry.js: `loadConfig(dotenvPath)`, `generateRunId()`, `ensureFeatureId(specPath)`, `buildPayload(runData)`, `compressArtifact(content)`, `sendTelemetry(payload, config)`, `retryQueue(queuePath, sendFn)`. The telemetry-config command logic is also inlined in tests — match the masking format (`****last4`) and output format exactly.

package/.blueprint/features/feature_pipeline-telemetry/story-failed-queue-retry.md

@@ -0,0 +1,53 @@
+# Story — Failed Send Queue and Retry
+
+### User story
+As a platform administrator, I want failed telemetry sends to be queued silently and retried at the start of the next pipeline run so that transient network issues do not cause data loss and never interrupt pipeline execution.
+
+---
+
+### Context / scope
+- Failed payloads are appended to `.claude/telemetry-failed.json`
+- Retry happens at pipeline start (before Step 1 processing) on subsequent runs
+- All failure handling is silent: no output to user on queue write or retry
+- The queue has a maximum depth (implementation-defined, e.g. 50 entries); oldest entries are dropped on overflow
+
+---
+
+### Acceptance criteria
+
+**AC-1 — Failed send is silently queued; pipeline continues**
+- Given telemetry is active and the HTTP POST fails (network error or non-2xx response),
+- When the send attempt completes,
+- Then the payload is appended to `.claude/telemetry-failed.json`, no error or warning is output to the user, and the pipeline continues normally.
+
+**AC-2 — Queued payloads are retried at the start of the next run**
+- Given `.claude/telemetry-failed.json` contains one or more queued payloads,
+- When the next pipeline run starts (before Step 1),
+- Then `src/telemetry.js` attempts to send each queued payload to the configured endpoint.
+
+**AC-3 — Successfully retried entries are removed from the queue**
+- Given a queued payload is retried and the endpoint returns a 2xx response,
+- When the retry completes,
+- Then that entry is removed from `.claude/telemetry-failed.json`; remaining failed entries stay in the file.
+
+**AC-4 — Queue file is removed when all entries are successfully sent**
+- Given `.claude/telemetry-failed.json` exists with entries that are all successfully retried,
+- When the last entry is sent successfully,
+- Then `.claude/telemetry-failed.json` is deleted (or written as an empty array — implementation choice, file absence is acceptable).
+
+**AC-5 — Retry failures remain in queue silently**
+- Given a queued payload is retried and the send fails again,
+- When the retry completes,
+- Then the entry remains in `.claude/telemetry-failed.json` and no output is produced.
+
+**AC-6 — Queue does not grow unboundedly**
+- Given `.claude/telemetry-failed.json` already contains the maximum allowed entries,
+- When a new send failure occurs,
+- Then the oldest entry is dropped and the new payload is appended, keeping the queue at the maximum depth.
+
+---
+
+### Out of scope
+- CLI command to inspect or clear the failed queue (file inspection only)
+- Configurable retry delay or backoff (retry happens at next pipeline start, no timer)
+- Retry of payloads when telemetry URL is unconfigured

package/.blueprint/features/feature_pipeline-telemetry/story-identifiers.md

@@ -0,0 +1,47 @@
+# Story — Run and Feature Identifiers
+
+### User story
+As a platform administrator, I want each pipeline run to carry a unique `runId` and each feature spec to carry a stable `featureId` so that I can correlate telemetry events with local history and track the same feature across multiple retries.
+
+---
+
+### Context / scope
+- `runId`: UUID v4, generated at pipeline start (Step 5 of SKILL.md), stored in working context and in the history entry
+- `featureId`: UUID v4, written into FEATURE_SPEC.md YAML frontmatter by Alex on first creation only
+- Both identifiers are generated using Node.js built-in `crypto.randomUUID()` — no external library
+
+---
+
+### Acceptance criteria
+
+**AC-1 — runId generated at pipeline start for every run**
+- Given a pipeline run is initiated,
+- When the pipeline reaches Step 5 of SKILL.md,
+- Then a UUID v4 `runId` is generated and stored in the working context for use throughout that run.
+
+**AC-2 — runId is stored in the history entry**
+- Given a pipeline run completes (successfully or with failure),
+- When the history entry is written to `.claude/pipeline-history.json`,
+- Then the entry includes the `runId` generated at pipeline start.
+
+**AC-3 — featureId written into FEATURE_SPEC.md frontmatter on first creation**
+- Given Alex creates a new FEATURE_SPEC.md that has no YAML frontmatter `featureId`,
+- When Alex writes the file,
+- Then a UUID v4 `featureId` is added to the YAML frontmatter of FEATURE_SPEC.md.
+
+**AC-4 — featureId is never regenerated if already present**
+- Given FEATURE_SPEC.md already contains a `featureId` in its YAML frontmatter,
+- When Alex processes the feature spec (on a re-run or update),
+- Then the existing `featureId` value is preserved unchanged.
+
+**AC-5 — runId is unique per run even for the same feature**
+- Given the same feature is run twice (e.g., after a failure and retry),
+- When both pipeline runs complete,
+- Then each run's history entry contains a different `runId`, while both FEATURE_SPEC.md entries retain the same `featureId`.
+
+---
+
+### Out of scope
+- Exposing `runId` in any user-visible CLI output
+- User-configurable or manually set `runId` or `featureId`
+- `featureId` for artifacts other than FEATURE_SPEC.md

package/.blueprint/features/feature_pipeline-telemetry/story-init-integration.md

@@ -0,0 +1,48 @@
+# Story — Init Command Integration (.env Template and .gitignore)
+
+### User story
+As a developer initialising a new murmur8 project, I want the `init` command to create a commented-out telemetry template in `.env` and ensure `.env` is protected by `.gitignore` so that I know telemetry exists and cannot accidentally commit credentials.
+
+---
+
+### Context / scope
+- `murmur8 init` runs `src/init.js` which copies framework files to the target project
+- `.env` file is at the project root; it is optional — telemetry is inactive if absent
+- `.gitignore` must include `.env` to prevent accidental credential commits
+- If `.env` already exists, the template block is appended (not overwritten) only if not already present
+
+---
+
+### Acceptance criteria
+
+**AC-1 — `.env` created with commented telemetry template when absent**
+- Given the target project has no `.env` file,
+- When `murmur8 init` is run,
+- Then a `.env` file is created at the project root containing a commented-out block documenting `MURMUR8_TELEMETRY_URL` and `MURMUR8_TELEMETRY_KEY`.
+
+**AC-2 — `.env` template appended when file already exists**
+- Given the target project already has a `.env` file that does not contain the murmur8 telemetry template block,
+- When `murmur8 init` is run,
+- Then the commented-out telemetry template block is appended to the existing `.env` file without modifying existing content.
+
+**AC-3 — `.env` not modified if template already present**
+- Given the target project has a `.env` file that already contains the murmur8 telemetry template block,
+- When `murmur8 init` is run,
+- Then the `.env` file is not modified (no duplicate block appended).
+
+**AC-4 — `.env` added to `.gitignore` when absent from it**
+- Given the target project has a `.gitignore` file that does not contain `.env`,
+- When `murmur8 init` is run,
+- Then `.env` is appended to `.gitignore`.
+
+**AC-5 — `.gitignore` not modified if `.env` already listed**
+- Given the target project's `.gitignore` already contains `.env`,
+- When `murmur8 init` is run,
+- Then `.gitignore` is not modified (no duplicate entry added).
+
+---
+
+### Out of scope
+- Emitting a user-visible notice that `.env` was created (silent operation, matching overall telemetry design)
+- Validating that existing `.env` values are correct
+- Creating or modifying `.gitignore` if neither `.gitignore` nor `.env` exist (no `.gitignore` needed without a `.env`)

package/.blueprint/features/feature_pipeline-telemetry/story-payload-send.md

@@ -0,0 +1,54 @@
+# Story — Telemetry Payload Construction and Send
+
+### User story
+As a platform administrator, I want a structured JSON event payload to be POST-ed to my telemetry endpoint at the end of each pipeline run so that I have complete execution data including identifiers, timings, stage statuses, and compressed artifacts.
+
+---
+
+### Context / scope
+- Send occurs at pipeline end (Step 12 of SKILL.md) via `src/telemetry.js`
+- Payload is a JSON body sent via HTTP POST using Node.js built-in `https`/`http` modules — no external HTTP library
+- Artifacts (FEATURE_SPEC.md and `story-*.md` files) are gzip-compressed with `zlib` and base64-encoded before inclusion
+- Send is fire-and-forget: the pipeline does not wait for confirmation beyond a reasonable timeout
+
+---
+
+### Acceptance criteria
+
+**AC-1 — Payload contains required identity and run fields**
+- Given telemetry is active and a pipeline run completes,
+- When the payload is constructed,
+- Then it includes: `runId`, `featureId`, `featureSlug`, `status` (success/failure), `startedAt`, `completedAt`, and `durationMs`.
+
+**AC-2 — Payload includes per-stage timing and status**
+- Given a pipeline run completes with one or more stages executed,
+- When the payload is constructed,
+- Then the `stages` block includes each executed stage with its `name`, `status`, and `durationMs`.
+
+**AC-3 — Artifacts are gzip-compressed and base64-encoded**
+- Given FEATURE_SPEC.md and any `story-*.md` files exist for the feature,
+- When the payload is constructed,
+- Then the `artifacts` block contains each file keyed by filename, with its content gzip-compressed (zlib) and base64-encoded.
+
+**AC-4 — Feedback block omitted when `--no-feedback` is used**
+- Given the pipeline is run with the `--no-feedback` flag,
+- When the payload is constructed,
+- Then the `feedback` block is absent from the payload.
+
+**AC-5 — Successful send produces no user-visible output**
+- Given telemetry is active and the HTTP POST returns a 2xx response,
+- When the send completes,
+- Then no message, log line, or output is written to stdout or stderr.
+
+**AC-6 — Payload sent with correct Content-Type header**
+- Given telemetry is active,
+- When the POST request is made,
+- Then the request includes the header `Content-Type: application/json`.
+
+---
+
+### Out of scope
+- Real-time or streaming telemetry (end-of-run POST only)
+- Telemetry for non-pipeline commands (`history`, `queue`, `validate`, etc.)
+- Encryption of payload beyond HTTPS transport
+- Validating or enforcing HTTPS on the configured URL (though a warning may be emitted for `http://`)

package/.blueprint/features/feature_pipeline-telemetry/story-telemetry-activation.md

@@ -0,0 +1,54 @@
+# Story — Telemetry Activation & Configuration
+
+### User story
+As a platform administrator, I want to activate pipeline telemetry by setting a URL in `.env` so that murmur8 sends structured execution data to my observability endpoint without requiring code changes.
+
+---
+
+### Context / scope
+- Configuration via `.env` file at project root and/or real environment variables
+- Activation is determined solely by the presence of `MURMUR8_TELEMETRY_URL`
+- Absence of the URL means telemetry is fully inactive — no output, no side effects
+
+---
+
+### Acceptance criteria
+
+**AC-1 — Telemetry inactive when URL is absent**
+- Given `MURMUR8_TELEMETRY_URL` is not set in `.env` or in the process environment,
+- When a pipeline run completes,
+- Then no HTTP request is made, no queue file is created, and no output is produced.
+
+**AC-2 — Telemetry active when URL is set in `.env`**
+- Given `MURMUR8_TELEMETRY_URL` is set to a valid URL in `.env`,
+- When a pipeline run completes,
+- Then `src/telemetry.js` POSTs the payload to that URL.
+
+**AC-3 — Real environment variable takes precedence over `.env`**
+- Given `MURMUR8_TELEMETRY_URL` is set to `https://env-value.example.com` in the process environment,
+- And `.env` contains `MURMUR8_TELEMETRY_URL=https://dotenv-value.example.com`,
+- When telemetry resolves the endpoint,
+- Then the request is sent to `https://env-value.example.com` (the process env value).
+
+**AC-4 — API key sent as Authorization header when set**
+- Given `MURMUR8_TELEMETRY_KEY` is set (in `.env` or environment),
+- When the telemetry POST is made,
+- Then the request includes the header `Authorization: Bearer <key>`.
+
+**AC-5 — Authorization header omitted when key is absent**
+- Given `MURMUR8_TELEMETRY_KEY` is not set,
+- When the telemetry POST is made,
+- Then no `Authorization` header is included in the request.
+
+**AC-6 — Same precedence rule applies to API key**
+- Given `MURMUR8_TELEMETRY_KEY` is set in both the process environment and `.env` with different values,
+- When telemetry resolves the key,
+- Then the process environment value is used.
+
+---
+
+### Out of scope
+- Opt-out flag (absence of URL is the opt-out mechanism)
+- Validating or enforcing HTTPS on the configured URL
+- Telemetry for non-pipeline CLI commands (`history`, `queue`, etc.)
+- Any third-party `.env` parsing library (manual parsing only)

package/.blueprint/features/feature_pipeline-telemetry/story-telemetry-config-command.md

@@ -0,0 +1,52 @@
+# Story — telemetry-config CLI Command
+
+### User story
+As a platform administrator, I want to run `murmur8 telemetry-config` to view the current telemetry configuration so that I can confirm the endpoint is configured correctly and check the failed-send queue depth — without exposing the API key in plaintext.
+
+---
+
+### Context / scope
+- New CLI command: `murmur8 telemetry-config` (registered in `bin/cli.js`, handled by `src/commands/telemetry-config.js`)
+- Reads configuration from `.env` and process environment (same precedence rules as telemetry module)
+- Displays configured URL; masks the API key; shows failed queue depth
+
+---
+
+### Acceptance criteria
+
+**AC-1 — Command displays configured URL**
+- Given `MURMUR8_TELEMETRY_URL` is set,
+- When `murmur8 telemetry-config` is run,
+- Then the output includes the full configured URL.
+
+**AC-2 — API key is masked in output**
+- Given `MURMUR8_TELEMETRY_KEY` is set to a non-empty value,
+- When `murmur8 telemetry-config` is run,
+- Then the output displays the key in masked form (e.g. `sk-****1234` showing only the last 4 characters) and never the full plaintext value.
+
+**AC-3 — Key shown as "not set" when absent**
+- Given `MURMUR8_TELEMETRY_KEY` is not configured,
+- When `murmur8 telemetry-config` is run,
+- Then the output indicates no key is configured (e.g. `not set`).
+
+**AC-4 — Command shows telemetry as inactive when URL is absent**
+- Given `MURMUR8_TELEMETRY_URL` is not set,
+- When `murmur8 telemetry-config` is run,
+- Then the output clearly indicates telemetry is inactive (e.g. `status: inactive`).
+
+**AC-5 — Failed queue depth is displayed**
+- Given `.claude/telemetry-failed.json` exists with N entries,
+- When `murmur8 telemetry-config` is run,
+- Then the output includes the number of queued failed sends (e.g. `failed queue: 3 entries`).
+
+**AC-6 — Failed queue shown as zero when file is absent**
+- Given `.claude/telemetry-failed.json` does not exist,
+- When `murmur8 telemetry-config` is run,
+- Then the output shows a failed queue depth of 0.
+
+---
+
+### Out of scope
+- A `--test` flag to send a synthetic ping to the endpoint
+- Editing or clearing configuration via this command (read-only display)
+- Displaying the full contents of the failed send queue

package/README.md

@@ -148,6 +148,7 @@ This updates `.blueprint/agents/`, `.blueprint/templates/`, `.blueprint/ways_of_
 | `npx murmur8 feedback-config set <key> <value>` | Modify feedback settings |
 | `npx murmur8 murm-config` | View murmuration pipeline configuration |
 | `npx murmur8 murm-config set <key> <value>` | Modify murmuration settings |
+| `npx murmur8 telemetry-config` | View telemetry configuration and failed queue depth |
 
 ## Skill usage
 
@@ -298,6 +299,7 @@ murmur8 includes these built-in modules for observability and self-improvement:
 | **stack** | Configurable tech stack detection and configuration |
 | **cost** | Token usage tracking and cost estimation per stage |
 | **diff-preview** | Pre-commit change review with user confirmation |
+| **telemetry** | Opt-in audit layer — POSTs structured run data to a configured endpoint for corpus building and enterprise usage monitoring |
 
 ### How They Work Together
 
@@ -515,6 +517,58 @@ npx murmur8 cost-config reset
 
 Cost data is stored in `pipeline-history.json` alongside timing and feedback data.
 
+## Pipeline Telemetry
+
+An opt-in audit and data collection layer. When a telemetry endpoint is configured, each completed pipeline run POSTs a structured event payload to that endpoint. If no endpoint is configured, the feature is completely silent — no output, no side effects.
+
+### Activation
+
+The `murmur8 init` command creates a `.env` file at your project root with a commented-out telemetry template:
+
+```bash
+# Remove # to enable
+MURMUR8_TELEMETRY_URL=https://your-ingest-endpoint.com/events
+MURMUR8_TELEMETRY_KEY=your-api-key   # optional — sent as Authorization: Bearer
+```
+
+Real environment variables take precedence over `.env`, making it straightforward to configure in CI/CD without storing credentials in files. `.env` is automatically added to `.gitignore` during init.
+
+### What gets sent
+
+| Field | Description |
+|-------|-------------|
+| `runId` | UUID v4 unique to this pipeline execution |
+| `featureId` | UUID stable across retries — written into FEATURE_SPEC.md frontmatter once by Alex |
+| `identity` | Git user name/email, repo remote URL, org ID, murmur8 version |
+| `run` | Slug, status, start/end timestamps, per-stage timings and statuses, feedback ratings |
+| `artifacts` | Feature spec and story files, gzip + base64 encoded |
+
+`featureId` enables cross-run correlation: all retries of the same feature share one `featureId` while each execution gets a unique `runId`. This lets you query "all runs ever attempted for this feature" and trace evolution over time.
+
+### Reliability
+
+Sends are non-blocking and never interrupt the pipeline. On failure (network error, timeout, non-2xx), the payload is silently queued to `.claude/telemetry-failed.json` and retried at the start of the next run.
+
+### Viewing configuration
+
+```bash
+npx murmur8 telemetry-config
+
+# Example output:
+# status:       active
+# url:          https://your-endpoint.com/events
+# api key:      ****1234
+# failed queue: 0 entries
+```
+
+### Enterprise use
+
+murmur8 telemetry is designed for self-hosted enterprise endpoints — there is no central collection service. Each organisation configures its own ingest URL. This enables:
+
+- **Usage monitoring** — who ran what pipeline, on which repo, when
+- **Audit trail** — `runId` + `commitHash` + `gitUser` provides an immutable trace of AI-assisted code changes
+- **Corpus building** — aggregate feature specs and stories across teams to analyse and improve pipeline quality
+
 ## Murmuration
 
 Run multiple feature pipelines simultaneously using git worktrees for isolation. Each feature gets its own worktree and branch, allowing true parallel development without conflicts.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "murmur8",
-  "version": "4.5.1",
+  "version": "4.6.0",
   "description": "Multi-agent workflow framework for automated feature development",
   "main": "src/index.js",
   "bin": {

package/src/commands/telemetry-config.js

@@ -0,0 +1,16 @@
+/**
+ * telemetry-config command - View telemetry configuration and queue status
+ */
+const { loadConfig, formatTelemetryConfig } = require('../telemetry');
+
+const description = 'View telemetry configuration and failed-send queue status';
+
+const QUEUE_PATH = '.claude/telemetry-failed.json';
+
+async function run(_args) {
+  const config = loadConfig('.env');
+  const output = formatTelemetryConfig(config, QUEUE_PATH);
+  console.log(output);
+}
+
+module.exports = { run, description };

package/src/index.js

@@ -94,6 +94,9 @@ const {
   markWorktreeAborted,
   getPromptText
 } = require('./diff-preview');
+const { loadConfig, generateRunId, ensureFeatureId, buildPayload, compressArtifact,
+        enqueueFailure, retryQueue, ensureDotenv, ensureGitignore, formatTelemetryConfig
+      } = require('./telemetry');
 const tools = require('./tools');
 const theme = require('./theme');
 
@@ -159,6 +162,17 @@ module.exports = {
   setStackConfigValue,
   detectStackConfig,
   displayStackConfig,
+  // Telemetry module exports
+  loadConfig,
+  generateRunId,
+  ensureFeatureId,
+  buildPayload,
+  compressArtifact,
+  enqueueFailure,
+  retryQueue,
+  ensureDotenv,
+  ensureGitignore,
+  formatTelemetryConfig,
   // Tools module (model native features)
   tools,
   // Theme module (murmuration visual theming)

package/src/init.js

@@ -3,6 +3,7 @@ const path = require('path');
 
 const { detectStackConfig, writeStackConfig, CONFIG_FILE: STACK_CONFIG_FILE } = require('./stack');
 const { prompt } = require('./utils');
+const { ensureDotenv, ensureGitignore } = require('./telemetry');
 
 const PACKAGE_ROOT = path.resolve(__dirname, '..');
 const TARGET_DIR = process.cwd();
@@ -176,6 +177,10 @@ async function init() {
     console.log('Stack config already exists, skipping detection');
   }
 
+  // Ensure .env template and .gitignore entry for telemetry
+  ensureDotenv(TARGET_DIR);
+  ensureGitignore(TARGET_DIR);
+
   console.log(`
 murmur8 initialized successfully!
 

package/src/telemetry.js

@@ -0,0 +1,198 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const zlib = require('zlib');
+const crypto = require('crypto');
+
+// ---------------------------------------------------------------------------
+// loadConfig — parse .env line by line; real process.env takes precedence
+// ---------------------------------------------------------------------------
+function loadConfig(dotenvPath) {
+  const fileVars = {};
+  try {
+    const lines = fs.readFileSync(dotenvPath, 'utf8').split('\n');
+    for (const line of lines) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('#')) continue;
+      const eqIdx = trimmed.indexOf('=');
+      if (eqIdx === -1) continue;
+      const key = trimmed.slice(0, eqIdx).trim();
+      const val = trimmed.slice(eqIdx + 1).trim();
+      fileVars[key] = val;
+    }
+  } catch (_) { /* file absent or unreadable — ignore */ }
+
+  const rawUrl = process.env.MURMUR8_TELEMETRY_URL ?? fileVars.MURMUR8_TELEMETRY_URL ?? '';
+  const rawKey = process.env.MURMUR8_TELEMETRY_KEY ?? fileVars.MURMUR8_TELEMETRY_KEY ?? '';
+
+  let url = null;
+  try { url = rawUrl ? (new URL(rawUrl), rawUrl) : null; } catch (_) { url = null; }
+
+  return { url, key: rawKey || null };
+}
+
+// ---------------------------------------------------------------------------
+// generateRunId — crypto UUID v4
+// ---------------------------------------------------------------------------
+function generateRunId() {
+  return crypto.randomUUID();
+}
+
+// ---------------------------------------------------------------------------
+// ensureFeatureId — reads/writes featureId into YAML frontmatter
+// ---------------------------------------------------------------------------
+function ensureFeatureId(specPath) {
+  const content = fs.readFileSync(specPath, 'utf8');
+  const fmMatch = content.match(/^---\n([\s\S]*?)\n---\n/);
+
+  if (fmMatch) {
+    const fmBody = fmMatch[1];
+    const idMatch = fmBody.match(/^featureId:\s*(.+)$/m);
+    if (idMatch) return idMatch[1].trim();
+
+    // Frontmatter exists but no featureId — insert it
+    const newId = generateRunId();
+    const newFm = `---\nfeatureId: ${newId}\n${fmBody}\n---\n`;
+    fs.writeFileSync(specPath, newFm + content.slice(fmMatch[0].length));
+    return newId;
+  }
+
+  // No frontmatter — prepend
+  const newId = generateRunId();
+  fs.writeFileSync(specPath, `---\nfeatureId: ${newId}\n---\n${content}`);
+  return newId;
+}
+
+// ---------------------------------------------------------------------------
+// buildPayload — assembles telemetry payload; omits feedback when empty
+// ---------------------------------------------------------------------------
+function buildPayload(runData) {
+  const { runId, featureId, slug, status, startedAt, completedAt,
+          totalDurationMs, stages, artifacts, feedback } = runData;
+
+  const run = { featureId, slug, status, startedAt, completedAt, totalDurationMs };
+  if (stages) run.stages = stages;
+  if (feedback && typeof feedback === 'object' && Object.keys(feedback).length > 0) {
+    run.feedback = feedback;
+  }
+
+  const payload = { runId, run };
+  if (artifacts) payload.artifacts = artifacts;
+  return payload;
+}
+
+// ---------------------------------------------------------------------------
+// compressArtifact — gzip + base64 (synchronous)
+// ---------------------------------------------------------------------------
+function compressArtifact(content) {
+  return zlib.gzipSync(Buffer.from(content, 'utf8')).toString('base64');
+}
+
+// ---------------------------------------------------------------------------
+// enqueueFailure — appends to queue; caps at 50; creates file if absent
+// ---------------------------------------------------------------------------
+function enqueueFailure(payload, queuePath) {
+  let queue = [];
+  try {
+    queue = JSON.parse(fs.readFileSync(queuePath, 'utf8'));
+    if (!Array.isArray(queue)) queue = [];
+  } catch (_) { queue = []; }
+
+  queue.push(payload);
+  if (queue.length > 50) queue = queue.slice(queue.length - 50);
+  fs.writeFileSync(queuePath, JSON.stringify(queue, null, 2));
+}
+
+// ---------------------------------------------------------------------------
+// retryQueue — calls sendFn per entry; removes successes; writes remaining
+// ---------------------------------------------------------------------------
+function retryQueue(queuePath, sendFn) {
+  let queue;
+  try {
+    queue = JSON.parse(fs.readFileSync(queuePath, 'utf8'));
+    if (!Array.isArray(queue)) return;
+  } catch (_) { return; }
+
+  const remaining = [];
+  for (const entry of queue) {
+    const ok = sendFn(entry);
+    if (!ok) remaining.push(entry);
+  }
+  fs.writeFileSync(queuePath, JSON.stringify(remaining, null, 2));
+}
+
+// ---------------------------------------------------------------------------
+// ensureDotenv — creates/appends .env with commented telemetry template
+// ---------------------------------------------------------------------------
+const DOTENV_MARKER = 'MURMUR8_TELEMETRY_URL';
+const DOTENV_TEMPLATE = `
+# murmur8 Telemetry — remove comments and set values to enable
+# MURMUR8_TELEMETRY_URL=https://your-endpoint.example.com/events
+# MURMUR8_TELEMETRY_KEY=your-api-key
+`;
+
+function ensureDotenv(targetDir) {
+  const envPath = path.join(targetDir, '.env');
+  try {
+    const existing = fs.readFileSync(envPath, 'utf8');
+    if (existing.includes(DOTENV_MARKER)) return;
+    fs.writeFileSync(envPath, existing + DOTENV_TEMPLATE);
+  } catch (_) {
+    fs.writeFileSync(envPath, DOTENV_TEMPLATE.trimStart());
+  }
+}
+
+// ---------------------------------------------------------------------------
+// ensureGitignore — adds .env to .gitignore; creates .gitignore if absent
+// ---------------------------------------------------------------------------
+function ensureGitignore(targetDir) {
+  const giPath = path.join(targetDir, '.gitignore');
+  try {
+    const existing = fs.readFileSync(giPath, 'utf8');
+    const lines = existing.split('\n').map(l => l.trim());
+    if (lines.includes('.env')) return;
+    fs.writeFileSync(giPath, existing + (existing.endsWith('\n') ? '' : '\n') + '.env\n');
+  } catch (_) {
+    fs.writeFileSync(giPath, '.env\n');
+  }
+}
+
+// ---------------------------------------------------------------------------
+// formatTelemetryConfig — returns formatted config string
+// ---------------------------------------------------------------------------
+function formatTelemetryConfig(config, queuePath) {
+  const { url, key } = config;
+  const status = url ? 'active' : 'inactive';
+
+  let maskedKey = 'not set';
+  if (key) {
+    maskedKey = key.length > 4 ? `****${key.slice(-4)}` : '****';
+  }
+
+  let queueDepth = 0;
+  try {
+    const q = JSON.parse(fs.readFileSync(queuePath, 'utf8'));
+    if (Array.isArray(q)) queueDepth = q.length;
+  } catch (_) { /* file absent or corrupt */ }
+
+  return [
+    `Telemetry status : ${status}`,
+    `URL              : ${url || 'not set'}`,
+    `API key          : ${maskedKey}`,
+    `Failed queue     : ${queueDepth} entries`,
+  ].join('\n');
+}
+
+module.exports = {
+  loadConfig,
+  generateRunId,
+  ensureFeatureId,
+  buildPayload,
+  compressArtifact,
+  enqueueFailure,
+  retryQueue,
+  ensureDotenv,
+  ensureGitignore,
+  formatTelemetryConfig,
+};