You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* chore: baseline remove-fuzzy-match-operator planning artifacts
Feature file, interview notes, DoD in product_definition.md, and test stubs
for removing ~= (APPROXIMATELY_EQUAL) operator.
* feat(condition): remove ~= fuzzy match operator
Squash-merge feature/remove-fuzzy-match-operator.
Removes the ~= fuzzy match operator from condition evaluation,
updates loader to reject unknown operators, and migrates
loader behavior tests to unit tests.
* release: v1.0.0 First Stone
* fix: align @id format and test conventions with established patterns
- Feature file: @id:remove-fuzzy-match-NNN → @id:<8-char-hex>
- Test functions: test_remove_fuzzy_match_NNN → test_remove_fuzzy_match_operator_<hex>
- Docstrings: Given/When/Then → Given:/When:/Then: (with colons)
- README: remove BPMN/SCXML comparison paragraph
* fix: remove deprecated License classifier (PEP 639)
-**Remove fuzzy match operator**: `~=` (APPROXIMATELY_EQUAL) removed from the specification and reference implementation; flows using `~=` now produce `FlowParseError` with state context
9
+
10
+
### Changed
11
+
12
+
-**Condition operators reduced from 7 to 6**: `==`, `!=`, `>=`, `<=`, `>`, `<`
13
+
-**`flowr/domain/condition.py`**: removed `APPROXIMATELY_EQUAL` enum value, `~=` from operator prefix map, and approximate comparison logic
14
+
-**`flowr/domain/loader.py`**: added `_validate_condition_operators()` to reject `~=` in all when-clause forms (inline dict, list-form, named references) with `FlowParseError`
15
+
-**Specification documents**: `flow_definition_spec.md`, `glossary.md`, `system.md`, `product_definition.md` updated to list exactly 6 operators
16
+
-**ADR_20260426_fuzzy_match_algorithm.md**: deprecated with removal notice
17
+
-**README.md**: banner image uses absolute URL for PyPI rendering, guard conditions explicitly list 6 operators, documentation links use absolute URLs
18
+
-**pyproject.toml**: version bumped to 1.0.0, status promoted to Production/Stable, Documentation URL points to spec page, added PyPI classifiers
19
+
20
+
### Removed
21
+
22
+
-`~=` condition operator (APPROXIMATELY_EQUAL) — no longer a valid operator in the flowr specification
23
+
- 6 obsolete tests referencing `~=` parsing and evaluation
24
+
3
25
All notable changes to this project will be documented in this file.
Copy file name to clipboardExpand all lines: README.md
+47-31Lines changed: 47 additions & 31 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,52 +1,58 @@
1
1
<divalign="center">
2
2
3
-
<imgsrc="docs/assets/banner.svg"alt="flowr — non-deterministic state machine specification to knead workflows"width="100%"/>
3
+
<imgsrc="https://raw.githubusercontent.com/nullhack/flowr/main/docs/assets/banner.svg"alt="flowr — non-deterministic state machine specification to knead workflows"width="100%"/>
**Define workflow state machines in YAML. Validate, query, and track them from the terminal.**
13
+
**A declarative, validatable YAML format for non-deterministic state machine workflows.**
14
+
15
+
[Read the specification →](https://nullhack.github.io/flowr/)
14
16
15
17
</div>
16
18
17
19
---
18
20
19
-
> **⚠️ Beta — do not install.** This project is under active development. The API, package structure, and configuration may change without notice until the first stable release.
21
+
## The specification
20
22
21
-
You write a flow definition in YAML. flowr checks that it is structurally valid, tells you what states exist and which transitions are available, and keeps track of where you are — across invocations, across subflows. One specification format. One CLI. No runtime engine, no side effects, no opinions about what your workflow should *do* — only what it *is* and whether it *holds together*.
23
+
flowr defines what a workflow **is** — its states, transitions, guard conditions, subflows — not what it **does**. No execution engine. No side effects. No opinions about retries, timeouts, or error handling. A YAML file declares structure. A validator checks integrity. Tools query, track, and visualise. [The format is the foundation.](https://nullhack.github.io/flowr/)
22
24
23
-
---
25
+
What the specification covers:
24
26
25
-
## Who is this for?
27
+
-**States** with unique ids, per-state attributes, and transition mappings
28
+
-**Transitions** that resolve to state ids or declared exit names
29
+
-**Guard conditions** gated by evidence-based expressions using 6 operators (`==`, `!=`, `>=`, `<=`, `>`, `<`)
30
+
-**Named condition groups** reusable across transitions on the same state
31
+
-**Subflows** with call-stack semantics — push on entry, pop on exit
32
+
-**Within-flow cycles** for iterative workflows
33
+
-**Validation rules** — structural integrity checks independent of any runtime
26
34
27
-
### Agent Operators — Persist workflow state across CLI invocations
35
+
What the specification does **not** cover:
28
36
29
-
You run `flowr check`, then `flowr transition`, then `flowr check` again — each time passing the flow name and current state by hand. Or you let sessions track it: `flowr session init deploy-flow`, `flowr --session transition approve`, `flowr --session check`. The session file remembers where you are. Push into a subflow; pop back out. No state to reconstruct, no context to pass.
30
-
31
-
### Developers — Validate and query workflow definitions from code or terminal
32
-
33
-
You write a flow YAML. You need to know: is it valid? Which states can I reach from here? Does this transition have guard conditions? `flowr validate`, `flowr states`, `flowr next`, `flowr check` answer these questions — from the terminal for humans, from the Python library for tools.
### Tool Authors — Build on a specification, not a runtime
36
-
37
-
flowr defines a YAML format for non-deterministic state machines with per-state attributes, guard conditions, and subflows. The validator enforces structural constraints. The library parses flows into dataclasses. No execution engine, no side-effect hooks — a clean foundation for editors, visualizers, or orchestration layers.
41
+
→ **[Full specification with examples and visual diagrams](https://nullhack.github.io/flowr/)**
38
42
39
43
---
40
44
41
-
## What it does
45
+
## The reference implementation
46
+
47
+
This repository contains a Python reference implementation — a CLI and library that validates, queries, and tracks flow definitions conforming to the specification. The specification is the contract; this code is one tool that honours it.
42
48
43
49
```
44
50
flowr validate deploy.yaml → valid: True
45
51
flowr states deploy.yaml → prepare, execute, review
**Query.** States, transitions, conditions, attributes — ask any question the flow can answer.
58
64
59
-
**Sessions.** Init, show, set-state, transition, list. Subflow push/pop for nested workflows. Auto-enters initial subflow on `session init`. One `--session` flag turns any command session-aware (including `validate` and `states`).
65
+
**Sessions.** Init, show, set-state, transition, list. Subflow push/pop for nested workflows. Auto-enters initial subflow on `session init`. One `--session` flag turns any command session-aware.
60
66
61
67
**Config.**`flowr config` shows where every value comes from — default, pyproject.toml, or CLI override.
You build editors, visualizers, CI systems, or orchestration layers. You need a structural format for workflow state machines — not an execution engine. The flowr specification gives you states, transitions, guard conditions, and subflows in a declarative YAML format with a conforming validator. Any tool can parse it. [Read the spec.](https://nullhack.github.io/flowr/)
160
+
161
+
### Agent operators
162
+
163
+
You run `flowr check`, then `flowr transition`, then `flowr check` again — each time passing the flow name and current state by hand. Or you let sessions track it: `flowr session init deploy-flow`, `flowr --session transition approve`, `flowr --session check`. The session file remembers where you are. Push into a subflow; pop back out. No state to reconstruct, no context to pass.
164
+
165
+
### Developers
166
+
167
+
You write a flow YAML. You need to know: is it valid? Which states can I reach from here? Does this transition have guard conditions? `flowr validate`, `flowr states`, `flowr next`, `flowr check` answer these questions — from the terminal for humans, from the Python library for tools.
168
+
169
+
---
170
+
149
171
## CLI Reference
150
172
151
173
| Command | Description |
@@ -192,18 +214,12 @@ Hexagonal architecture. Domain has no infrastructure dependencies. CLI is the pr
192
214
193
215
---
194
216
195
-
## Why does this exist
196
-
197
-
No existing YAML standard covers non-deterministic state machine workflows with per-state agent assignment and filesystem-as-source-of-truth. Existing solutions (XState, SCXML, Serverless Workflow, BPMN) target execution engines or deterministic workflows. flowr fills this gap: a declarative, validatable, toolable format for workflows that branch on evidence rather than control flow.
Copy file name to clipboardExpand all lines: docs/adr/ADR_20260426_fuzzy_match_algorithm.md
+1-1Lines changed: 1 addition & 1 deletion
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,7 +2,7 @@
2
2
3
3
## Status
4
4
5
-
Accepted
5
+
**Deprecated** — The `~=` operator was removed from the flowr specification in v1.0.0 (2026-05-06). It was unused in practice and added unnecessary complexity. See feature `remove-fuzzy-match-operator`. This ADR is retained for historical reference only.
0 commit comments