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 v6.1.6. All @hellmai/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.

v7.0.0 — Governed execution, security closure, and faster delivery

Released 2026-08-25. v7 is a major release that aligns the public package family on one governed execution contract. It combines the launch-quality hardening from INIT-101, Campus EMIT completion from INIT-102, trajectory supervision from INIT-103, gate-cycle economics from INIT-104, and the security/dependency boundary closure from INIT-105.

What changes for consumers

• Node.js 26 and pnpm 11 are the primary supported CLI toolchain. All published packages must use the same v7 version.
• The deprecated @hellmai/lumenflow-core compatibility package is removed. Import from the owning public package and run pnpm lumenflow:upgrade --latest before the first v7 WU.
• Pack Contract v2 and signed OCI distribution make digest, signature, SBOM, provenance, namespace ownership, quarantine, and exact-digest readback part of the pack trust boundary.
• Web workspace operations authenticate before bounded body/file access, bind targets to the exact caller workspace, reject symlink escapes, and use host-pinned executables.
• Connected Compute refuses remote cleartext bearer transport and replaces --token <secret> with --token-env <UPPERCASE_NAME> so credentials stay out of argv and shell history.
• New installs derive a safe path-scoped test_incremental when project evidence supports it. Safety and normal tests share one execution, uncovered changed code gets one related sweep, and unchanged prep checkpoints are reused by wu:done.
• Full tests remain fail-closed for unsafe or missing scope, test configuration or untracked changes, failed change detection, main-snapshot comparison, or explicit --full-tests. Fresh completion checks remain separate.

Operations and release posture

• Releases refuse red or unverified main, exercise packed consumers before publish, and publish the Reliability Operations pack as signed OCI with SBOM/provenance and exact public readback.
• Gate runs report all applicable failures, include cross-package parity suites, scope builds to the affected graph, and use bounded repository-level concurrency.
• Append-only gate-attempt evidence and trajectory stagnation/thrashing signals let orchestrators redirect unproductive loops without prescribing a model, vendor, or automatic termination.
• Campus reads now use persisted state, GPU attestation emits verified quote evidence, and the EMIT energy contract is shared across SDKs.

Upgrade checklist

1. Install Node.js 26 and pnpm 11, then run pnpm lumenflow:upgrade --latest.
2. Replace every @hellmai/lumenflow-core import using the generated migration guidance.
3. Review workspace.yaml gate commands and keep the generated test_incremental distinct from test_full.
4. Reinstall/pin packs through the governed v2/OCI path and run pnpm lumenflow:doctor.
5. Update Connected Compute enrolment to --token-env; use HTTPS except for explicit loopback development endpoints.
6. If you host the local workspace web runtime, set LUMENFLOW_WEB_CLI_ENTRYPOINT to the absolute, host-owned pack-install.js entrypoint. Pack install fails closed when it is absent or relative.
7. Run one complete wu:prep/wu:done cycle and preserve any project-owned fresh completion checks.

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 @hellmai/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)
• @hellmai/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 @hellmai/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

• @hellmai/lumenflow-core removal. Its 23 subpath exports were deprecated in v5.8.11, and the @hellmai/lumenflow-core package was physically removed in v7. See the migration guide.
• v5.8.11 had no runtime breaks. At that release, the @hellmai/lumenflow-cli, @hellmai/lumenflow-core root barrel, and MCP coordination APIs remained unchanged; v7 later removed @hellmai/lumenflow-core.

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 @hellmai/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 @hellmai/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.