Compatibility Matrix

The current published stable is v6.1.6. LumenFlow publishes its public npm packages together; use one matching version across a consumer repository.

Public packages

Package	Purpose
@hellmai/lumenflow-agent	Agent definitions and skill loading
@hellmai/lumenflow-cli	Command-line surface and setup tooling
@hellmai/lumenflow-conductor-sdk	Conductor event and handler contracts
@hellmai/lumenflow-control-plane-sdk	Control-plane transport and configuration contracts
@hellmai/lumenflow-host	Runtime host composition
@hellmai/lumenflow-initiatives	Initiative projections and planning support
@hellmai/lumenflow-kernel	Task, scope, policy, evidence, and pack primitives
@hellmai/lumenflow-mcp	MCP server, tools, and resources
@hellmai/lumenflow-memory	Session memory, signals, and checkpoints
@hellmai/lumenflow-metrics	Flow and delivery metrics
@hellmai/lumenflow-packs-agent-runtime	Governed agent-runtime pack
@hellmai/lumenflow-packs-campus	Campus domain pack
@hellmai/lumenflow-packs-protocol-adapters	Protocol-adapter pack
@hellmai/lumenflow-packs-reliability-operations	Read-only reliability investigation pack
@hellmai/lumenflow-packs-sidekick	Workspace productivity pack
@hellmai/lumenflow-packs-software-delivery	WUs, lanes, gates, and worktree lifecycle pack
@hellmai/lumenflow-runtime	Kernel runtime and scheduling services
@hellmai/lumenflow-shims	Git and process safety shims
@hellmai/lumenflow-surfaces	HTTP and other runtime surfaces

The upgrade command preserves the dependency sections and optional packages already selected by the consumer:

pnpm lumenflow:upgrade --latest
pnpm lumenflow:doctor

Runtime requirements

Surface	Minimum	Recommended	Notes
@hellmai/lumenflow-cli executables	Node.js 26.0.0	Node.js 26.8.1 Current	The published engine rejects earlier releases
Public library APIs	Declared package engine	Node.js 26.8.1 Current	Check the installed package manifest
pnpm	11.4.0	12.3.4 Current	Primary package-manager path
npm	10.0.0	12.0.2	Supported for local package installation

Caution

The scoped CLI package is not itself an executable because it exposes many named binaries. Install it locally, then run the injected pnpm lumenflow and pnpm wu:* scripts.

Current instead of LTS

LumenFlow intentionally tracks the current stable Node.js 26 line. Node.js 24 remains an LTS release, but consumers and CI use Node.js 26 so the published contract, generated workflows, and local development match the user’s selected latest-stable toolchain.

Operating systems

This section states the platform contract, not the state of any installation today. The contract is being implemented across the cross-platform initiative’s phases 2 to 5; until those land, verify actual behaviour on your own host rather than inferring it from this page.

LumenFlow’s platform contract covers Windows, macOS, and Linux natively, under one equal guarantee envelope: the same lifecycle results and evidence, the same enforcement of lifecycle hooks and generated CI, the same owner isolation for protected state and credentials, the same enforced-or-refused sandbox rule, the same Connected Compute availability rule, and the same literal performance ceilings with no per-operating-system multiplier. Differences between hosts are differences of mechanism — which confinement primitive, which secret store, which executable name — never a weaker promise.

Where a guarantee cannot be met on a host, the surface refuses and says why rather than proceeding unprotected. Reporting the posture in force on the running host through pnpm lumenflow:doctor is part of the contract and is not yet implemented. ADR-033 records the contract in full.

Process invocation (implemented). Every LumenFlow-assembled argv-form pnpm, npm and npx spawn — across gates, prep, claim, dependency commands, doctor, upgrade, release, approvals, init, completion, recovery and the shims — resolves its executable through one shared helper before spawning, and never sets shell: true. On Linux and macOS the binary is passed through unchanged, so behaviour is byte-identical to before. On Windows it becomes either a resolved native executable or an explicit cmd.exe /d /s /v:off /c invocation whose argument string LumenFlow escapes itself, quoting and caret-escaping being two alternative forms rather than both at once. A shim that is not on PATH fails closed with a named error, and an argument carrying a line break is refused rather than escaped.

This does not cover the shell-string command paths that keep their shell treatment deliberately — operator-authored gates.commands.* entries and the release pipeline’s runCommand strings, where the host shell performs the lookup itself. A ratchet fails the build on any new bare package-manager spawn, including through exec/execSync, an already-resolved executable constant, an import alias, or a local exec-shaped indirection.

Windows behaviour is verified by platform-parameterized unit tests with injected host facts and by a round-trip model of the documented cmd.exe parsing stages. Neither is execution evidence: running on a real Windows or macOS runner is the cross-platform CI leg, which has not landed yet, so verify on your own host before relying on it.

Shim entry guards and path semantics (implemented). The git and pnpm safety shims (@hellmai/lumenflow-shims) and the prompt-linter CLI entry each invoke main() behind import.meta.main rather than the older process.argv[1]-based comparison, which never matches on Windows because import.meta.url is a file:// URL while process.argv[1] is a native backslash path — the guard failed silently, exiting 0 having done nothing. Home-directory, PATH, and git/pnpm-executable discovery resolve per platform (os.homedir(), path.delimiter, a where/which lookup with a .cmd/.exe-aware target) instead of assuming POSIX. Both copies of resolvePlanFile (--file, initiative related_plan) recognize a Windows drive-letter or UNC absolute path, not only a leading /. The gates-latest.log convenience pointer falls back to a plain file copy when symlink creation is denied (the expected shape on an unprivileged Windows account), instead of silently reporting failure. ADR-033 section 2 records the entry-point guard convention and section 3 records the symlink/copy convention; the repository’s internal building-block notes cover the shim and path-resolution detail.

Owner-isolation principal encoding (implemented). The owner-only access boundary (@hellmai/lumenflow-host/filesystem/owner-isolation) accepts any real Windows account name when building the icacls access-control entry, including one containing a space — the Windows OOBE default account name is a two-word “First Last” such as “John Smith” — a backslash (the DOMAIN\user form), parentheses, or non-ASCII characters. The principal is embedded verbatim, never hashed or replaced with a synthetic token, because icacls must resolve a real account to grant it access. Only characters that would make the access-control entry’s own grammar ambiguous or exploitable are refused: the : delimiter the port injects, a comma (icacls’s multi-grantee separator), an asterisk (its wildcard/SID marker), a double quote, and a forward slash (its flag prefix) — none of which ever appears in a real Windows account name. This encoding is unverified-by-construction in the same sense as the rest of this section: the decision logic is exercised through injected seams, and denied-access proof against a real Windows DACL is a separate, not-yet-landed CI leg.

MCP protocol compatibility

Surface	Certified protocol	Legacy posture
@hellmai/lumenflow-mcp stdio	2026-07-28	Rejected by the served LumenFlow configuration
Authenticated Streamable HTTP	2026-07-28	Rejected; modern requests are stateless
TypeScript SDK v2 integration	2026-07-28	Explicit compatibility is available downstream
LumenFlow v7 release evidence	2026-07-28 only	Legacy connections are non-certifying

LumenFlow-owned clients pin the certified revision and fail closed on downgrade. Modern discovery is server/discover with per-request metadata and headers; it does not use initialize or Mcp-Session-Id. LumenFlow’s ordinary task_* tools are not the io.modelcontextprotocol/tasks extension, which is not advertised.

Workspace configuration

Current workspaces have two distinct lane surfaces:

• top-level lanes are kernel LaneSpec entries with scope permissions;
• software_delivery.lanes.definitions are delivery lane definitions with names and code paths.

Use pnpm lane:create, pnpm lane:edit, and pnpm config:set rather than copying a legacy flat configuration or hand-editing workspace.yaml. See Workspace Spec for the complete current shape.

Gate preset compatibility

Preset	Primary tools
node	Prettier, ESLint, TypeScript, Vitest or the repository test script
python	Ruff, mypy, pytest
go	gofmt, golangci-lint, go vet, go test
rust	rustfmt, clippy, cargo check, cargo test
dotnet	dotnet format, build, test
java	google-java-format, SpotBugs, javac, Maven/JUnit
ruby	RuboCop, Sorbet, RSpec
php	PHP-CS-Fixer, PHPStan, Psalm, PHPUnit

The repository’s configured commands remain authoritative. Run pnpm gates to verify the actual consumer configuration.

Version support

Major line	Status	Recommended action
7.x	Current	Stay on the latest published patch
6.x	Upgrade path	Run pnpm lumenflow:upgrade --latest and review migration output
5.x and earlier	End of life	Upgrade through 6.x migration guidance, then to current

v7 requires Node.js 26 and pnpm 11 for the primary CLI path, removes the deprecated @hellmai/lumenflow-core package, adopts Pack Contract v2 and signed OCI distribution, and tightens web, process, credential, registry, and lifecycle security boundaries. Read the v7 changelog before upgrading automation that depends on package paths, pack transport, or legacy gate configuration.

Release-specific breaking changes and migrations live in the Changelog. Do not infer current behavior from an old major’s configuration examples.

Agent hosts and repository access

LumenFlow supports any agent host that can read LUMENFLOW.md and invoke the public CLI or MCP surface. Host-specific instruction files and hooks are project-owned, not versioned LumenFlow interfaces. Git hosting permissions determine who may clone or push; LumenFlow only requires an attributable local Git identity for governed work.

Lifecycle enforcement remains provider-neutral: repository-owned delegators protect the manifest, receipts, journals, hooks, and managed CI block, while lumenflow:doctor exposes their compliance state. Only enforced is certifying; disabled, missing, stale, tampered, unavailable, or uninstalled consumers cannot claim certification. A hostile unsandboxed process with the same OS-user authority can replace local evidence, so stronger isolation requires an OS sandbox or protected remote/server authority.

Verify an installation

node --version
pnpm list @hellmai/lumenflow-cli
pnpm lumenflow:doctor
pnpm lumenflow:commands