murmur8 4.5.1 → 4.7.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://`)