diff --git a/examples/status.journal b/examples/status.journal
new file mode 100644
index 000000000..06c821230
--- /dev/null
+++ b/examples/status.journal
@@ -0,0 +1,11 @@
+1/1 uncleared
+  (a)  1
+  (b)  1
+
+1/2 ! pending
+  (a)  1
+  ! (b)  1
+
+1/3 * cleared
+  (a)  1
+  * (b)  1
diff --git a/hledger-lib/Hledger/Data/Types.hs b/hledger-lib/Hledger/Data/Types.hs
index d6b326e5a..4ab2a2ac0 100644
--- a/hledger-lib/Hledger/Data/Types.hs
+++ b/hledger-lib/Hledger/Data/Types.hs
@@ -180,6 +180,12 @@ type TagName = Text
 type TagValue = Text
 type Tag = (TagName, TagValue)  -- ^ A tag name and (possibly empty) value.
 
+-- | The status of a transaction or posting, recorded with a status mark
+-- (nothing, !, or *). What these mean is ultimately user defined.
+-- Calling the unmarked state "Uncleared" creates some ambiguity 
+-- but is traditional in Ledger/hledger so we keep it (#564).
+-- Calling the type "Cleared..." might also be confusing, just Status
+-- would be better but that's currently used as a Query constructor.
 data ClearedStatus = Uncleared | Pending | Cleared
   deriving (Eq,Ord,Typeable,Data,Generic)
 
diff --git a/tests/journal/status.test b/tests/journal/status.test
index 5b2f102e9..b6062c4b5 100644
--- a/tests/journal/status.test
+++ b/tests/journal/status.test
@@ -1,80 +1,108 @@
-# 1. the status field can contain nothing,
-hledger -f- print
-<<<
-2015/1/1 x
-  (a)  1
+## parsing
+
+# 1. transactions and postings have status marks which are nothing, ! or *
+hledger -fstatus.journal print
 >>>
-2015/01/01 x
+2017/01/01 uncleared
     (a)               1
-
->>>=0
-
-# 2. or !
-hledger -f- print
-<<<
-2015/1/1 ! x
-  (a)  1
->>>
-2015/01/01 ! x
-    (a)               1
-
->>>=0
-
-# 3. or *
-hledger -f- print
-<<<
-2015/1/1 * x
-  (a)  1
->>>
-2015/01/01 * x
-    (a)               1
-
->>>=0
-
-# 4. --cleared matches * only
-hledger -f- print --cleared
-<<<
-2015/1/1 x
-  (a)  1
-2015/1/1 ! x
-  (b)  1
-2015/1/1 * x
-  (c)  1
->>>
-2015/01/01 * x
-    (c)               1
-
->>>=0
-
-# 5. --pending matches ! only
-hledger -f- print --pending
-<<<
-2015/1/1 x
-  (a)  1
-2015/1/1 ! x
-  (b)  1
-2015/1/1 * x
-  (c)  1
->>>
-2015/01/01 ! x
     (b)               1
 
+2017/01/02 ! pending
+    (a)               1
+    ! (b)             1
+
+2017/01/03 * cleared
+    (a)               1
+    * (b)             1
+
 >>>=0
 
-# 6. --uncleared matches all except *
-hledger -f- print --uncleared
+# 2. other characters will be considered part of the description
+hledger -f- print desc:%
 <<<
-2015/1/1 x
-  (a)  1
-2015/1/1 ! x
-  (b)  1
-2015/1/1 * x
-  (c)  1
+2017/01/01 % 
 >>>
-2015/01/01 x
-    (a)               1
+2017/01/01 %
 
-2015/01/01 ! x
+>>>=0
+
+## matching with flags
+
+# 3. --cleared matches * only
+hledger -fstatus.journal print --cleared
+>>>
+2017/01/03 * cleared
+    (a)               1
+    * (b)             1
+
+>>>=0
+
+# 4. --pending matches ! only
+hledger -fstatus.journal print --pending
+>>>
+2017/01/02 ! pending
+    (a)               1
+    ! (b)             1
+
+>>>=0
+
+# 5. --uncleared matches everything but *
+hledger -fstatus.journal print --uncleared
+>>>
+2017/01/01 uncleared
+    (a)               1
     (b)               1
 
+2017/01/02 ! pending
+    (a)               1
+    ! (b)             1
+
 >>>=0
+
+# 6. only one of these flags (the last) takes effect
+hledger -fstatus.journal register --uncleared --pending --cleared
+>>>
+2017/01/03 cleared              (a)                              1             1
+                                (b)                              1             2
+>>>= 0
+
+# 7. these flags work with other commands
+hledger -fstatus.journal balance -N --uncleared
+>>>
+                   2  a
+                   2  b
+>>>=0
+
+## matching with status: query
+
+# 8. status:* matches * only
+hledger -fstatus.journal print status:*
+>>>
+2017/01/03 * cleared
+    (a)               1
+    * (b)             1
+
+>>>=0
+
+# 9. status:! matches ! only
+hledger -fstatus.journal print status:!
+>>>
+2017/01/02 ! pending
+    (a)               1
+    ! (b)             1
+
+>>>=0
+
+# 10. status: matches everything but *
+hledger -fstatus.journal print status:
+>>>
+2017/01/01 uncleared
+    (a)               1
+    (b)               1
+
+2017/01/02 ! pending
+    (a)               1
+    ! (b)             1
+
+>>>=0
+
diff --git a/tests/misc/query-status.test b/tests/misc/query-status.test
deleted file mode 100644
index f0b6970d0..000000000
--- a/tests/misc/query-status.test
+++ /dev/null
@@ -1,76 +0,0 @@
-# filtering by transaction status
-
-# 1. with --cleared, print shows cleared transactions only
-hledger -f- print --cleared
-<<<
-2010/1/1 x
-  a  1
-  b
-
-2010/1/2 * x
-  a  1
-  b
-
-2010/1/3 *
-  a  1
-  b
->>>
-2010/01/02 * x
-    a               1
-    b
-
-2010/01/03 *
-    a               1
-    b
-
->>>=0
-
-# 2. with --uncleared, shows uncleared transactions only
-hledger -f- print --uncleared
-<<<
-2010/1/1 x
-  a  1
-  b
-
-2010/1/2 * x
-  a  1
-  b
-
-2010/1/3 *
-  a  1
-  b
->>>
-2010/01/01 x
-    a               1
-    b
-
->>>=0
-
-# 3. can also have per-posting cleared status
-hledger -f- register --cleared
-<<<
-2012/1/1
-  a  1
-  *b  2
-  * c  4
-  d
->>>
-2012/01/01                      b                                2             2
-                                c                                4             6
->>>= 0
-
-
-# 4. also works with balance as shown, same as ledger. Hmm.
-hledger -f- balance --uncleared
-<<<
-2012/1/1
-  a  1
-  *b  2
-  d
-
->>>
-                   1  a
-                  -3  d
---------------------
-                  -2
->>>=0