Product Policies

These are binding product policies that apply across all LumenFlow deployments and consumer integrations. They define non-negotiable guarantees and constraints on capability scope, documentation, and cross-orchestrator coordination.

Cross-Platform Parity

Windows, macOS, and Linux are first-class peers: same lifecycle, same enforcement envelope, same performance targets, same trust guarantees.

Reduced-trust or degraded modes are crash-safe fallbacks only, never a platform default.
A genuine OS-primitive gap requires explicit named human sign-off; a documented delta alone is not sufficient.
New code with platform-conditional behavior must justify itself against this policy.

Rationale: LumenFlow serves as a software delivery platform for agents across all major platforms. Allowing platform-specific limitations to become default behavior would fragment the user experience, complicate testing, and make cross-platform coordination unreliable. This policy ensures that feature parity is the norm and degradation is the exception.

Documentation Parity

Any new command, flag, technique, rule, operator-facing artifact, or behavioral change lands in arc42 AND Starlight, and is reflected in --help where a command surface changed.

This is an acceptance criterion on the introducing WU, not a follow-up. State “n/a” explicitly when a change is genuinely internal.

Rationale: Product documentation must be canonical and complete at ship time. Deferring docs to later WUs creates a window where operators lack the information needed to use or troubleshoot new features. Treating docs as a post-implementation concern has been observed to leave features undocumented for months or indefinitely. By making docs an acceptance criterion, this policy ensures that no feature ships without corresponding guidance.

Vendor Neutrality in Records

Never bake vendor, harness, or model names into WU specs, initiative records, ADRs, or framework code paths.

Records describe outcomes and capability tiers; the orchestrating agent maps tiers to concrete models from its own knowledge. Client/harness identifiers used for spawn mechanics (e.g. wu:brief --client <profile>) are legitimate — model prescriptions are not.

Rationale: LumenFlow is designed to work with any AI system capable of reading files and executing commands. Encoding vendor names into governance records creates a hard dependency on a specific vendor and prevents the system from serving as a multi-vendor coordination platform. This policy keeps the governance layer neutral and allows the product to integrate with any orchestrating system.

Cross-Orchestrator Communication

When orchestrators from different vendors or harnesses coordinate work on the same initiative (e.g., two orchestrators running in different harnesses managing the same wave), they MUST use LumenFlow’s own primitives for communication:

mem:signal — emit coordination signals (progress, blockers, handoff)
mem:inbox — poll for incoming signals from peer orchestrators
mem:context — retrieve relevant context (initiative state, WU details, policy)
Lifecycle state — claims, receipts, locks that are visible via the shared file system

Messages MUST carry verifiable anchors (WU IDs, commit SHAs, signal IDs, initiative IDs); unanchored directives are correctly refused.

Why not vendor-native channels? No vendor-native session channel (e.g., a harness-native session variable) spans vendors. Coordination that depends on such a channel is unavailable to peer orchestrators and does not count as working. LumenFlow primitives are vendor-agnostic and accessible to any system that can read files and emit signals.

Rationale: Multi-vendor orchestration requires a neutral coordination layer. Relying on vendor-native channels creates hidden dependencies on specific platforms and undermines the claim that the system is multi-vendor capable. Using LumenFlow’s primitives ensures that any orchestrator, regardless of vendor, can participate in coordination without needing vendor-specific knowledge.

Repo-Local Specifics

The Orchestration Topology policy documented in LUMENFLOW.local.md (a repo-local file, not published to this site) covers repo-local contention points (fleet-wide landing serialization, per-box gate-suite ceiling, legacy-client fence) and the topological rule that “one orchestrator per harness” avoids same-vendor coordination overhead.

These repo-local specifics remain in LUMENFLOW.local.md because they are tuning parameters for that deployment, not constraints that apply to all LumenFlow users. The cross-orchestrator communication rule (documented above) is product-level and applies universally; the contention points are specific to how that repository’s CI and fleet are organized.

arc42 Product Policies (docs/01-introduction-and-goals/product-policies.md) — full policy documentation, an internal arc42 reference not published to this site
Quality Goals — architectural principles driving LumenFlow design, documented in the internal arc42 reference, not yet published to this site
Lifecycle — initiative orchestration phases
ADR-023: Vendor-Agnostic Telemetry Stream Routing — messaging routing across vendors, an internal ADR not yet published to this site
ADR-118: Portable Coordination and Federation Boundary — multi-vendor coordination design, an internal ADR not yet published to this site