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
UN-3396 [MISC] Make Known Exceptions section optional
The "## Known Exceptions" section was previously mandatory — the
contract said absence meant "the contract is not being followed" and
the single line `None.` was required when the file had no exceptions.
In practice this is cargo culting. The baseline for Known Exceptions
is zero: most files will never have one because exceptions are rare by
definition. Mandating a `None.` placeholder on every file:
- Adds ~4 lines of noise per per-component file (trained readers to
skip the section)
- Gives the same failure mode as optional (`None.` written reflexively
without the author evaluating whether exceptions exist is
indistinguishable from a missing section)
- Defeats the purpose of the section when a real exception is added,
because readers have learned to scroll past it
Change the contract to require the section only when at least one
intentional, accepted exception exists. Absence of the section now
means "no known exceptions today" — equivalent to `None.` but without
the placeholder noise.
Also tightened the Known Exceptions definition to be explicit that an
entry documents an *evaluated, accepted* deviation, not "drift we
haven't decided about yet." Unevaluated drift belongs in the issue
tracker, not in a Known Exceptions entry. This is the lesson from the
ExecutionViewSet finding on PR #1908 — a Known Exception added for
unexamined drift would be fraud-by-documentation.
Files changed:
* design-rules/per-component-contract.md
- Section structure row #8 now says the section is optional and
describes the presence-only semantics.
- Known Exceptions format prose updated: explicit "optional", no
`None.` placeholder, entry semantics hardened to "evaluated,
accepted" only.
* backend/account_v2/DESIGN_RULES.md
* backend/workflow_manager/DESIGN_RULES.md
* unstract/connectors/DESIGN_RULES.md
* unstract/connectors/src/unstract/connectors/databases/DESIGN_RULES.md
* workers/shared/DESIGN_RULES.md
- Dropped the empty `## Known Exceptions` / `None.` block from each
prototype file. All 5 files now go straight from the last rule (or
horizontal rule) to `## Checklist`.
validate.sh still passes — nothing in the script depends on the
Known Exceptions section being present.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Copy file name to clipboardExpand all lines: design-rules/per-component-contract.md
+4-4Lines changed: 4 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -23,7 +23,7 @@ Every per-component `DESIGN_RULES.md` contains, in this order:
23
23
| 5 |`## Scope` — two-row table with `**Covers**` and `**Excludes**`|
24
24
| 6 |`## Read first` — table of files and why each binds here |
25
25
| 7 |`## Rules` — `R1`..`Rn`, each rendered as an `### R<N> — <title>` heading followed by a 4-row table (Severity / Why / Refs / Enforced by). If the component has no rules yet, the section contains the single line `No component-specific rules yet.`|
26
-
| 8 |`## Known Exceptions`— `### <descriptive title>`headings with a 3-row table (Rule / Why / Tracked in), OR the single line `None.`|
26
+
| 8 |`## Known Exceptions`(optional) — present *only* when at least one intentional, accepted exception exists. Each entry is a `### <descriptive title>`heading with a 3-row table (Rule / Why / Tracked in). Omit the section entirely when there are none.|
27
27
| 9 |`## Checklist` — single line linking to `definition-of-done.md`|
28
28
29
29
Place a `---` horizontal rule between major content sections (after the Contract pointer, after `Read first`, after `Rules`). They create the visual breaks that make the file scannable in a github diff or markdown preview but are not themselves "sections."
@@ -119,11 +119,11 @@ A rule with `Enforced by: not yet enforced` is still a real rule, but it is hone
119
119
|**Tracked in**| <issue tracker ID, ADR reference, or "permanent — see Why"> |
120
120
```
121
121
122
-
Exceptions are temporary by definition — they exist to record an accepted current violation, and they are removed when the violation is fixed. They are not numbered: stable IDs are for things you cite from outside, and exceptions are referred to by their topic, not by an ID. When an exception is removed, the heading simply disappears.
122
+
Exceptions are temporary by definition — they exist to record an accepted current violation, and they are removed when the violation is fixed. They are not numbered: stable IDs are for things you cite from outside, and exceptions are referred to by their topic, not by an ID. When an exception is removed, the heading simply disappears; when the last exception goes away, drop the whole `## Known Exceptions` section with it.
123
123
124
-
If there are no known exceptions, the section contains the single line `None.`. The section is mandatory — its absence means the contract is not being followed.
124
+
The section is **optional**. Include it only when at least one intentional, accepted exception exists. Absence of the section means "no known exceptions today" — do not write `None.` or a placeholder.
125
125
126
-
A `## Known Exceptions` entry is the *only* legitimate way for code to violate a rule without changing the rule. If the deviation is permanent, say so explicitly under `Tracked in:`. If the deviation is temporary, the tracker entry must hold the plan to remove it.
126
+
A `## Known Exceptions` entry is the *only* legitimate way for code to violate a rule without changing the rule. An entry documents an **evaluated, accepted** deviation, not "we discovered some drift we haven't decided about yet." Unevaluated drift belongs in the issue tracker, not here. If the deviation is permanent, say so explicitly under `Tracked in:`. If the deviation is temporary, the tracker entry must hold the plan to remove it.
0 commit comments