[emaarco]

Why

bpmn-cli had two flow-id modes: rename (default) and keep (--keep-flow-ids). Two modes meant two code paths through every command that changes a flow's ends, a stale-id warning, an env var and a lot of docs. With one mode, agents get a single contract: a flow whose id names its source and target always follows them.

What

• Keep mode removed: --keep-flow-ids, --no-keep-flow-ids, BPMN_KEEP_FLOW_IDS, the library option keepFlowIds, W_FLOW_ID_STALE with StaleFlowReport, the CLI's "flow ids kept" note and its E_NOT_FOUND hint.
• Keep-only move code removed: MovedFlows (putting a moved node's out-flow back with its id) and the flow-reuse paths in ElementMove, NodePlacement, SequenceFlows and FlowBridge.
• Internal switch kept: Doc.followFlowEnds stays, without CLI or API surface. BatchDrawing.isEngineOwned matches edges by flow id after removing undrawn nodes, so renaming bridged flows there would wrongly make an engine-made drawing look hand-made.
• Unchanged: the renamed from … report, and ids in other forms (Flow_0yq6cfd) are never renamed.
• Docs and skill no longer describe keep mode.

Verification

• New flow-ids-follow-ends.test.ts covers each path from the issue: add --after/--before/--flow, set source=/target=, remove with bridging, split, move (single and chained), and an id in another form staying put. Only set source= can change a flow's source; the other commands only retarget it.
• npm test (2350 passed), npm run typecheck, knip: clean. The chained-move result was compared against main and is identical.

Breaking changes

The flag, the env var and keepFlowIds are gone, with no deprecation release. Users who treat flow ids as an API (generated code, process tests) now get renames and must follow the renamed: report. A leftover --keep-flow-ids is rejected as an unknown option; a leftover BPMN_KEEP_FLOW_IDS is ignored.

Out of scope / Follow-ups

• [Feature]: Lint rule that flags sequence flow ids not naming their source and target #128: a lint rule that flags flow ids no longer naming their source and target, so drifted ids can still be found and fixed by an agent without a second mode in the engine.

Closes #126