Changelog

This is the narrative changelog — a hand-curated view grouped by initiative and release theme. For the mechanically generated per-release feed (every wu:done across every tag, newest first), see the auto-generated changelog.

The current published stable version is v5.18.3. All @lumenflow/* packages ship together; see the Compatibility Matrix for Node.js and package-manager support.

What is an initiative?

An initiative is a multi-WU feature set with a single architectural story. The narrative changelog groups work units by initiative so the cross-cutting story is readable; the auto-generated feed keeps per-release ordering for when you want the raw “what landed in v4.22” list.

v5.18.0 — Model-agnostic fleet lifecycle safety

Released 2026-06-14. v5.18.0 ships INIT-081, the fleet lifecycle safety sweep. The release protects active agent work from concurrent cleanup, adds a non-destructive restore path for missing active worktrees, reconciles stale delegation rows against WU truth, and makes broad review/audit work first-class in WU sizing.

This is a minor release because it changes public workflow behavior and recovery guidance without breaking existing WU specs.

What shipped

• Active/recent WU leases now block wu:prune --execute; recoverable tracked removals write quarantine audit evidence under .lumenflow/quarantine/worktrees/cleanup.jsonl.
• wu:recover --action restore recreates a missing active worktree from the lane branch without resetting WU status, branch, baseline/main metadata, or completion evidence.
• orchestrate:monitor reconciles delegation rows against WU YAML, done stamps, execution evidence, launch records, and signals before treating work as pending or stuck.
• flow:bottlenecks and flow:report now surface actionable cycle and lane-contention diagnostics instead of leaving orchestrators with all-zero ambiguity.
• review-audit is accepted as a sizing exception for broad read-heavy audits.
• Initiative plan-linking safely publishes local plan bodies, and skip-setup worktrees discover nested package manifests before projecting package-level node_modules symlinks.

Architecture and docs

The architecture decision is accepted as ADR-115 in the internal arc42-style architecture record set. The public Fleet Lifecycle Authority page mirrors the user-facing contract: lifecycle authority comes from WU/lane/ session/lease/branch/worktree/stamp/audit evidence, not provider names, model names, hosted runners, client UIs, or plugins.

Docs outcome: Both internal docs and Starlight docs.

Pack decision

No new pack is introduced in this release. Fleet lifecycle safety belongs to the kernel plus the Software Delivery Pack lifecycle because it governs every WU. Migration guidance: use governed restore/quarantine/reconciliation flows instead of raw Git worktree cleanup or destructive reset/reclaim recovery.

v5.17.0 — EMIT energy telemetry and provenance

Released 2026-06-13. v5.17.0 ships INIT-080, the Energy-to-the-Metal EMIT side. LumenFlow now has one shared emit:energy_meter_recorded event contract for joule observations across kernel runtime, SDKs, and pack emitters.

This is a minor release because it adds a new observation surface without breaking existing EMIT streams.

What shipped

• Shared SDK types, schemas, and fixtures for measured, modeled, and facility energy rows.
• Connected compute device support for joules measured through hardware-facing meter classes such as NVML/DCGM-style GPU telemetry, Linux powercap/RAPL, IPMI, and Redfish power distribution equipment interfaces.
• Managed inference modeling for per-run token energy where provider platforms expose usage but not meter-level joules.
• Campus Pack facility allocation via facility_energy, pue_applied, and provenance fields, without mixing carbon attribution into the kernel event.
• Provider-brand-free invariants that keep the public contract neutral and observation-only across live builders, SDK contracts, fixtures, and docs.

Architecture and docs

The architecture decision for the meter axis and provenance contract is accepted as ADR-114 in the internal architecture decision record set. The arc42-style internal architecture notes and the public Starlight EMIT energy page were updated together.

Docs outcome: Both internal docs and Starlight docs.

Pack decision

No new Energy Pack is introduced in this release. Run-grain connected compute energy belongs in the shared EMIT kernel/SDK surface, facility allocation stays with the Campus Pack, and lumenflow.cloud remains responsible for hosted attribution, carbon factors, proof assembly, and billing workflows.

v5.8.11 — Kernel hardening: writes-to-main, hex ports, monolith decomposition

Released 2026-05-22. v5.8.11 is the first release of an architectural sweep that closes a class of bugs at compile time, makes the kernel vendor-agnostic in code (not just intent), and decomposes the four worst files in the repo. v5.8.4 through v5.8.10 were tagged but never published — v5.8.11 is the first tag in this series to ship all 17 @lumenflow/* packages to npm.

If you have been holding back from upgrading because the framework felt internally inconsistent, this is the release that ratchets the internals so they cannot regress.

1. The “writes-to-main” bug class is closed at compile time

Every WU-lifecycle write now flows through a single facade, withMicroWorktreeAndPush({ operation, id, execute }), with pushOnly: true hardcoded. Paths use branded TypeScript types: WorktreePath for any mutating write, MainCheckoutPath only for read-only references to the main checkout. Cross-conversion requires an explicit unsafe constructor and shows up in code review.

The wrong path is a compile error, not a runtime surprise. An AST-based path-literal ratchet prevents the next regression from landing on main.

2. The kernel is vendor- and tool-agnostic in code, not just intent

Five hex ports define the kernel’s infrastructure seams:

• ISystemClock — now, sleep
• IProcessExecutor — spawn, exec (array-based, no shell strings)
• IEnvironmentAccessor — env reads with explicit allowlists
• ITelemetrySink — structured event emission
• IRandomnessSource — random IDs, jitter

Each port has a Node* adapter for production and a Memory* adapter for tests. Framework source no longer hardcodes Date.now(), child_process, process.env, console.*, or Math.random. Typed domain errors (GitError, RecoveryAnalysisError, PatrolError) replace generic throw new Error(), and a unified Logger contract threads correlation IDs through the lifecycle.

A hex-port-coverage ratchet enforces that infrastructure calls go through ports — tool integrations that follow now MUST keep mechanism in source and vendor names in workspace.yaml.

3. The four worst monoliths are gone

Four files over 2000 lines each have been decomposed into focused modules:

File	Before	After	Notes
runtime-tool-resolver.ts	2818 LOC	160 LOC	Most of the deletion was dead code
wu-spawn-prompt-builders.ts	2464 LOC	105 LOC	Plus 10 section modules
wu-done.ts	2316 LOC	1067 LOC	Plus 4 phase modules around an xstate orchestrator
init-templates.ts	2284 LOC	39 LOC	Plus 27 per-template files

File-size baselines are now ratcheted: every future change must reduce or hold these numbers, never grow them.

4. AST-based ratchets prevent regression

Architectural rules are enforced by CI, not aspiration. Each of these has a baseline file under tools/baselines/ that gates can only ratchet down:

• File-size baseline
• Path-literal guard (no hardcoded main-checkout paths in lifecycle code)
• Status-literal guard (no inline WU status strings)
• Hex-port-coverage (infrastructure calls go through ports)
• @lumenflow/core subpath exports baseline
• Branded-type usage
• Shell-injection guard (no shell strings in process execution)
• Console-call guard (use the Logger contract)
• Lane-coverage baseline

5. v5.8.11 is on npm

All 17 @lumenflow/* packages are published. v5.8.4 through v5.8.10 are stale tags — the publish workflow no longer fights itself on --access flags (each package’s publishConfig.access is authoritative) and the npm token requirements are now documented.

See the internal release process docs for npm token requirements (bypass_2fa: true is mandatory).

Migration notes

• Deprecated @lumenflow/core subpaths. 23 subpath exports are marked deprecated in v5.8.11. They still resolve but will be removed in a future major. See the migration guide.
• No runtime breaks. The architectural sweep is internal. Public APIs for @lumenflow/cli, @lumenflow/core root barrel, and MCP coordination surfaces are unchanged.

Conductor-mode kernel surfaces (v4.24)

Released 2026-04-18. Ten work units across five phases that turn the kernel’s outbound sync pipe from a 3-kind lifecycle stream into a 14-kind tagged-union event contract, plus a scope-gated tool surface and an agent-host reachability registry. This is the foundation that lets external control surfaces drive LumenFlow orchestration remotely without tailing agent-local files.

Phase 1 — Architectural ratification

• Architectural ratification: package boundary, tagged-union discriminant, schema versioning, sync cadence, scope grammar, and agent-host reachability classes pinned before downstream implementation. (6bf67bc63)

Phase 2 — SDK contract + emitters

• SDK contract: delegation registry, WUEvent mirror, and tagged-union SdkKernelEvent with 30 variants; schema_version bumped to 2. (155fb4468)
• Emitter module kernel-event-sync/ with buildKernelEventV2 factory for the 14 conductor kinds, including event_id idempotency. (59adc657a)

Phase 3 — Inbound control surface

• GET /tools discovery endpoint on the kernel HTTP surface with pack-aware metadata. (fae015778)
• Per-tool auth scopes on POST /tools/:name, capability-scoped tokens, and the 403 missing_scopes response shape. (2652491a9)

Phase 4 — Reachability + sync cadence

• Agent-host enrollment registers reachable HTTP URL and reachability class (reverse-tunnel, public, lan, unreachable). (756556cc0)
• Sub-minute sync cadence: the control-plane event subscriber now runs in sidecar mode, started by wu:claim / agent:session, driven by control_plane.sync_interval. (7c17252ac)
• Narrow conductor emissions (orchestration:next_safe_actions_updated, org:capacity_snapshot) wired into orchestrate:init-status. (c53389e67)

Phase 5 — Follow-ups

• Coverage backfill to 94% on the agent-session heartbeat path. (df497db3d)
• wu:prep commit-order gate: test(…) must precede feat(…) under software_delivery.gates.tdd_ordering. (ae18766f5)

v4.23 — Orchestration becomes its own feature area

Released 2026-04. Three work units that complete the orchestration control-plane work: orchestration docs move to their own top-level section, reconciliation learns capacity and integrity, and the control-plane SDK becomes the single contract every surface speaks.

• Unify the orchestration contract on @lumenflow/control-plane-sdk: CLI, MCP, and tests all import the same shapes. (13113bd59)
• Elevate /orchestration/ to a top-level Starlight feature area with five pages (overview, lifecycle, state machine, artifact bundle, capacity + integrity, SDK). (9e2aca9f6)
• Wire capacity + integrity evidence into reconciliation so orchestration refuses to advance on contaminated or over-capacity workspaces. (ef192d1f8)

v4.22 — Evidence-based control plane lands

Released 2026-04. The bulk of the control-plane initiative ships: the evidence-based control-plane state model is ratified, launch receipts become durable artifacts, the 10-state classifier replaces the collapsed-to-in_progress story, MCP coordination tools expose the same JSON the CLI writes, and the docs catch up.

Control-plane foundation

• Evidence-based control plane ratified: one initiative state model, many launchers. (8047ec90c)
• Persist launch receipts and logical-wave artifacts for initiative orchestration. (3f2d1bad2)
• Reconcile orchestration status surfaces from execution evidence. (3d23e7fda)
• Reconciliation, integrity checks, and capacity-aware advancement. (989aeff09)
• Publish the orchestration state contract in @lumenflow/control-plane-sdk. (a0ef4b1fb)
• Expose the orchestration JSON through MCP coordination tools. (d5e916076)
• Update orchestration docs and templates for the evidence-based control plane. (06809fcd5)
• Align Starlight orchestration docs with the control-plane contract. (033d3494e)

Drift repairs + docs plumbing

• Repair CLI test drift blocking template-backed docs WUs. (f571d87f7)
• Scope docs-only test planning for template-backed docs WUs. (cd9ca4d00)
• Allow template-backed markdown docs in documentation WUs. (ca3559723)
• Repair core test drift blocking orchestration docs source updates. (781833e6c)
• Repair methodology regression drift blocking docs-source gates. (21421a953)
• Repair MCP parity drift. (6943ce79b)
• Repair MCP / CLI integration parity drift. (5fce38b01)
• Repair CLI truth drift blocking docs-source gates. (1194ed7cb)

Earlier releases

For the full history from v1.0.0 through current, including patch releases and version-alignment bumps, see the auto-generated changelog. Every wu:done since the first tag is represented there.