From c2cc053dcecb8a28650da4befb2c1d523b624bae Mon Sep 17 00:00:00 2001
From: "mintlify[bot]" <109931778+mintlify[bot]@users.noreply.github.com>
Date: Sun, 10 May 2026 13:37:23 +0000
Subject: [PATCH] docs(legal): document DeadlineGuard fail-closed behavior

Generated-By: mintlify-agent
---
 legal/guards.mdx | 69 +++++++++++++++++++++++++++++++++++++++++++++---
 1 file changed, 66 insertions(+), 3 deletions(-)

diff --git a/legal/guards.mdx b/legal/guards.mdx
index 6b87b749..39a83c7d 100644
--- a/legal/guards.mdx
+++ b/legal/guards.mdx
@@ -66,13 +66,14 @@ print(result.difference_days)    # 13
 
 | Field | Type | Description |
 | --- | --- | --- |
-| `verified` | `bool` | Whether the claimed deadline matches the computed deadline |
+| `verified` | `bool` | Whether the claimed deadline matches the computed deadline. `False` when the term is ambiguous |
 | `signing_date` | `datetime` | Parsed signing date |
 | `claimed_deadline` | `datetime` | The deadline claimed by the LLM |
-| `computed_deadline` | `datetime` | The correct deadline computed by the guard |
+| `computed_deadline` | `Optional[datetime]` | The correct deadline computed by the guard. `None` when the term is ambiguous and no deterministic deadline can be computed |
 | `term_parsed` | `str` | The original term string |
-| `difference_days` | `int` | Absolute difference in days between claimed and computed |
+| `difference_days` | `Optional[int]` | Absolute difference in days between claimed and computed. `None` when the term is ambiguous |
 | `message` | `str` | Human-readable verification message |
+| `is_computable` | `bool` | `True` when the term parses into a deterministic deadline. `False` when the term is ambiguous (for example, "promptly", "reasonable period") or no recognizable time unit was found |
 | `verification_mode` | `str` | Always `"SYMBOLIC"` for legal verification |
 
 ### Features
@@ -83,6 +84,68 @@ print(result.difference_days)    # 13
 | **Holiday Support** | 200\+ countries via `python-holidays` |
 | **Leap Years** | Handles Feb 29 correctly |
 | **Natural Language** | Parses "2 weeks", "3 months", "1 year" |
+| **Fail-closed on ambiguity** | Returns `is_computable=False` and `computed_deadline=None` when the term has no numeric quantity or no recognizable time unit |
+
+### Fail-closed behavior on ambiguous terms
+
+`DeadlineGuard` does not invent deadlines from vague legal language. When the supplied `term` cannot be reduced to a concrete `(quantity, unit)` pair, the guard fails closed: it marks the result as unverified and returns `None` for the computed deadline rather than substituting a default.
+
+Two gates trigger fail-closed:
+
+1. **No numeric quantity in the term** — for example, `"forthwith"`, `"promptly"`, `"as soon as practicable"`, `"within a reasonable period"`.
+2. **A number is present but no recognizable time unit** — for example, `"30"` without `days`, `weeks`, `months`, or `years`.
+
+In both cases:
+
+- `verified` is `False`
+- `is_computable` is `False`
+- `computed_deadline` is `None`
+- `difference_days` is `None`
+- `message` explains that the term is unverifiable and requires human legal interpretation
+
+```python
+from qwed_legal import DeadlineGuard
+
+guard = DeadlineGuard(country="US")
+
+result = guard.verify(
+    signing_date="2026-01-15",
+    term="within a reasonable period",
+    claimed_deadline="2026-02-14",
+)
+
+print(result.verified)           # False
+print(result.is_computable)      # False
+print(result.computed_deadline)  # None
+print(result.difference_days)    # None
+print(result.message)
+# ⚠️ UNVERIFIABLE: Term 'within a reasonable period' does not contain a
+# provable time quantity and unit. Cannot compute a deterministic deadline.
+# Ambiguous legal language (e.g., 'reasonable period', 'promptly') requires
+# human legal interpretation.
+```
+
+Always branch on `is_computable` before trusting `computed_deadline`:
+
+```python
+if not result.is_computable:
+    # Ambiguous term — escalate to a human reviewer.
+    ...
+elif not result.verified:
+    # Computable, but the claimed deadline is wrong.
+    ...
+```
+
+#### Recognized time units
+
+A term is computable only when it contains both a number and one of the following unit keywords (case-insensitive):
+
+| Unit | Keywords |
+| --- | --- |
+| Days | `day`, `calendar` (optionally combined with `business`, `working`, or `work` for business days) |
+| Weeks | `week` |
+| Months | `month` |
+| Years | `year` |
 
 ### Calculate business days between dates