Add lifecycle telemetry transitions

[ncolesummers]

Summary

Closes #73.

Adds the transition layer that consumes loopworks.validation_report.v1 outcomes from #75 and turns them into durable run/step state changes plus ADR 0012 lifecycle telemetry. The implementation keeps OTel metric names centralized in src/lib/observability/metrics.ts, preserves existing validation artifacts instead of creating duplicates, and documents the required-skipped-gate blocking rule in the loop manifest guide.

What changed

• Added development-loop transition helpers for validation report application, run completion, and step retry behavior.
• Added centralized lifecycle metric helpers for run completion/duration, step duration/retries, and validation outcome/duration.
• Blocked downstream stages for failed validation, skipped required gates, and missing required gate results; optional skipped gates remain artifact-only and non-blocking.
• Made transition metric emission idempotent on replay and kept metrics post-transaction so persistence remains authoritative.
• Added redaction/safe-code handling for validation command metric attributes and retry/terminal reason metadata.
• Added PGlite-backed transition tests and metric contract tests.

Validation

TDD red evidence captured before production code:

• bun test tests/unit/observability/metrics.test.ts failed on missing recordDevelopmentLoopStepRetryMetric export.
• bun test tests/unit/loops/development-run-transitions.test.ts failed because @/lib/loops/development-run-transitions did not exist.
• Follow-up QA tests failed red for missing required gate blocking, duplicate lifecycle metrics on replay, sensitive command/reason handling, and missing persisted trace IDs in transition logs.

Green checks:

• bun test tests/unit/observability/metrics.test.ts
• bun test tests/unit/loops/development-run-transitions.test.ts
• bun run build
• bun run validate passed end-to-end: format, lint, agent-docs, markdownlint, typecheck, 231 Vitest tests, Storybook build, and 17 Playwright tests.

Reviewer focus

Please scrutinize the transition semantics around required skipped gates, missing required gate results, and idempotent metric emission. Those are the places where incorrect behavior would either advance runs too eagerly or double-count operational telemetry.

Co-authored-by: OpenAI Codex (GPT-5) codex@openai.com

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
loopworks	Ready	Preview, Comment	Jul 8, 2026 4:14am

[Copilot]

Pull request overview

Adds the transition layer that applies deterministic validation outcomes to durable development-loop run/step state, and emits ADR 0012 lifecycle telemetry via centralized OpenTelemetry metric helpers.

Changes:

• Added new lifecycle metric recorders for run completion/duration, step duration/retries, and validation outcome/duration (with cancellation spelling normalization and basic redaction for command attributes).
• Introduced applyDevelopmentLoopValidationReport, completeDevelopmentLoopRun, and retryDevelopmentLoopStep transition helpers with idempotent (replay) behavior and “metrics-after-transaction” emission.
• Documented the blocking semantics for failed validation and skipped required gates; added PGlite-backed transition tests and metric contract tests.

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
tests/unit/observability/metrics.test.ts	Extends metric contract coverage to include lifecycle metrics, sink failure safety, and command redaction.
tests/unit/loops/development-run-transitions.test.ts	Adds end-to-end tests for validation application, blocking rules, replay idempotency, trace ID logging, run completion metrics, and retry behavior.
src/lib/observability/metrics.ts	Centralizes new lifecycle metric instruments/attributes and adds command-attribute redaction + cancellation spelling normalization.
src/lib/loops/development-run-transitions.ts	Adds the new transition layer that persists validation/run/step state and emits lifecycle telemetry post-commit.
docs/loop-manifest.md	Documents required/optional gate blocking semantics for validation reports.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.