docs(gaps): classify each gap (standard vs gm2 leniency vs V3 bug)

The corpus is gcc's gm2 testsuite, so it mixes standard Modula-2 with
gm2 leniency.  Standard PIM/ISO forbids use-before-declaration except a
POINTER's base type, so the forward type/const cases (gap01-gap06,
subrange4/7/11, shift3/4, constsize2, setoverflow, setconst3) are NOT
missing language features -- gm2 resolves the whole declaration part and
V3 rejecting them is standard-conforming.

Add a `class` column: decl-order / iso/system / gm2-ext / v3-deviation /
impl-limit.  Note gap13 is a V3 deviation (ORD/CHR/... are predeclared
identifiers, not reserved words, so `PROCEDURE ORDL` is legal M-2).

docs/analysis_gaps.md

@@ -238,4 +238,10 @@ Next (recorded): forward *type* references in a `CONST` conversion
 family (partly a corpus-harness transitive-`.def` gap).
 
 Every gap above has a self-contained reproducer in `docs/gaps/`
-(`docs/gaps/README.md` indexes them by tag).
+(`docs/gaps/README.md` indexes them by tag, with a **class**:
+`decl-order` = gm2 accepting use-before-declaration, which strict
+Modula-2 forbids and V3 correctly rejects; `iso/system`; `gm2-ext`;
+`v3-deviation`; `impl-limit`).  In particular the forward *type/const*
+cases (`subrange4`/`7`/`11`, `shift3`/`4`, `constsize2`, `setoverflow`,
+`setconst3`) are **not standard Modula-2** — only a `POINTER`'s base type
+may be declared later.

docs/gaps/README.md

@@ -12,28 +12,48 @@ cd compiler && ./build.sh
 ./M2 ../docs/gaps/gap07_convert.mod     # prints the diagnostic on stdout
 ```
 
+## Classifying the gaps
+
+The corpus is **gcc's gm2 testsuite**, so "compiles on the corpus" mixes
+standard Modula-2 with **gm2 leniencies and extensions**.  Standard
+Modula-2 (PIM and ISO) requires **declaration before use**; the only
+forward reference the language allows is a **POINTER's base type** (for
+recursive/self-referential types).  V3 deliberately enforces that order,
+so the `decl-order` cases below are *not* missing language features —
+they are gm2 accepting non-conforming programs.
+
+The `class` column says what a fix would mean:
+
+- `decl-order` — gm2 resolves the whole declaration part; strict M-2
+  forbids the use-before-declaration.  **Not a standard feature.**
+- `iso/system` — a standard ISO Modula-2 / SYSTEM facility V3 lacks.
+- `gm2-ext` — a gm2/PIM extension or a leniency (not portable M-2).
+- `v3-deviation` — V3 is *stricter than the standard* (a V3 bug).
+- `impl-limit` — the language allows it; V3 has a fixed implementation
+  limit.
+
 ## Index
 
-| tag | file | diagnostic | corpus exemplars |
-| --- | --- | --- | --- |
-| `gap01-fwd-type-const-conv` | `gap01_fwd_type_const_conv.mod` | `undeclared identifier` | `subrange4`, `subrange7` |
-| `gap02-fwd-type-var` | `gap02_fwd_type_var.mod` | `undeclared identifier` | `subrange11` (procedure-local part) |
-| `gap03-fwd-type-heading` | `gap03_fwd_type_heading.mod` | `undeclared identifier` | `shift3`, `shift4` |
-| `gap04-fwd-const-bound` | `gap04_fwd_const_bound.mod` | `undeclared identifier` | `setconst3` |
-| `gap05-fwd-type-size` | `gap05_fwd_type_size.mod` | `undeclared identifier` | `constsize2` |
-| `gap06-fwd-setconst` | `gap06_fwd_setconst.mod` | `undeclared identifier` | `setoverflow` |
-| `gap07-convert-builtin` | `gap07_convert.mod` | `undeclared identifier` | `procconv2` |
-| `gap08-set-word-cast` | `gap08_val_cast_set_word.mod` | `not supported yet` | `constset`, `constset2`, `constset3`, `packed`, `bitset5`, `packed` |
-| `gap09-scalar-to-bytearray` | `gap09_scalar_to_bytearray.mod` | `invalid call` | `aochar`, `arrayofbyte`, `bytearray` |
-| `gap10-var-param-type` | `gap10_var_param_type.mod` | `invalid call` | `testparam2`, `testparam3` |
-| `gap11-bare-proc-stmt` | `gap11_bare_proc_stmt.mod` | `invalid call` | `tinyproc2`, `tinyproc4` |
-| `gap12-variant-empty-arms` | `gap12_variant_empty_arms.mod` | `invalid VarLabel` | `varient2`, `varient3`, `varient8`, `tsize`, `tsize2` |
-| `gap13-builtin-proc-name` | `gap13_builtin_proc_name.mod` | `ident expected` | `fileio.def`, `fileio.mod` |
-| `gap14-builtin-pragma` | `gap14_builtin_pragma.def` | `ident expected` | `builtin.def`, `builtin.mod` |
-| `gap15a-qualified-import` | `gap15a_qualified_import.mod` (+ `gap15_base.def`, `gap15_lib.def`) | `undeclared identifier` | `impf`, `impk`, `impl`, `impq` |
-| `gap15b-from-import` | `gap15b_from_import.mod` (+ `gap15_base.def`, `gap15_lib.def`) | `undeclared identifier` | `impi` |
-| `gap16-wide-set` | `gap16_wide_set.mod` | `not supported yet` | `settest1` |
-| `gap17-set-of-cardinal` | `gap17_set_of_cardinal.mod` | `not supported yet` | `settest3` |
+| tag | file | class | diagnostic | corpus exemplars |
+| --- | --- | --- | --- | --- |
+| `gap01-fwd-type-const-conv` | `gap01_fwd_type_const_conv.mod` | `decl-order` | `undeclared identifier` | `subrange4`, `subrange7` |
+| `gap02-fwd-type-var` | `gap02_fwd_type_var.mod` | `decl-order` | `undeclared identifier` | `subrange11` (procedure-local part) |
+| `gap03-fwd-type-heading` | `gap03_fwd_type_heading.mod` | `decl-order` | `undeclared identifier` | `shift3`, `shift4` |
+| `gap04-fwd-const-bound` | `gap04_fwd_const_bound.mod` | `decl-order` | `undeclared identifier` | `setconst3` |
+| `gap05-fwd-type-size` | `gap05_fwd_type_size.mod` | `decl-order` | `undeclared identifier` | `constsize2` |
+| `gap06-fwd-setconst` | `gap06_fwd_setconst.mod` | `decl-order` | `undeclared identifier` | `setoverflow` |
+| `gap07-convert-builtin` | `gap07_convert.mod` | `iso/system` | `undeclared identifier` | `procconv2` |
+| `gap08-set-word-cast` | `gap08_val_cast_set_word.mod` | `iso/system` | `not supported yet` | `constset`, `constset2`, `constset3`, `packed`, `bitset5` |
+| `gap09-scalar-to-bytearray` | `gap09_scalar_to_bytearray.mod` | `gm2-ext` | `invalid call` | `aochar`, `arrayofbyte`, `bytearray` |
+| `gap10-var-param-type` | `gap10_var_param_type.mod` | `gm2-ext` | `invalid call` | `testparam2`, `testparam3` |
+| `gap11-bare-proc-stmt` | `gap11_bare_proc_stmt.mod` | `gm2-ext` | `invalid call` | `tinyproc2`, `tinyproc4` |
+| `gap12-variant-empty-arms` | `gap12_variant_empty_arms.mod` | `gm2-ext` | `invalid VarLabel` | `varient2`, `varient3`, `varient8`, `tsize`, `tsize2` |
+| `gap13-builtin-proc-name` | `gap13_builtin_proc_name.mod` | `v3-deviation` | `ident expected` | `fileio.def`, `fileio.mod` |
+| `gap14-builtin-pragma` | `gap14_builtin_pragma.def` | `gm2-ext` | `ident expected` | `builtin.def`, `builtin.mod` |
+| `gap15a-qualified-import` | `gap15a_qualified_import.mod` (+ `gap15_base.def`, `gap15_lib.def`) | `iso/system` | `undeclared identifier` | `impf`, `impk`, `impl`, `impq` |
+| `gap15b-from-import` | `gap15b_from_import.mod` (+ `gap15_base.def`, `gap15_lib.def`) | `iso/system` | `undeclared identifier` | `impi` |
+| `gap16-wide-set` | `gap16_wide_set.mod` | `impl-limit` | `not supported yet` | `settest1` |
+| `gap17-set-of-cardinal` | `gap17_set_of_cardinal.mod` | `impl-limit` | `not supported yet` | `settest3` |
 
 Observed first diagnostics (line:col) at commit time:
 
@@ -58,6 +78,24 @@ gap16_wide_set.mod:5:29              not supported yet
 gap17_set_of_cardinal.mod:5:19       not supported yet
 ```
 
+## Why `gap01`–`gap06` are not standard Modula-2
+
+All six name an identifier before its declaration:
+
+```mod
+CONST low = ind0(-100);        (* ind0's TYPE section comes later *)
+TYPE  ind0 = [-100..100];
+```
+
+gm2 accepts this because it resolves the whole declaration part; PIM/ISO
+Modula-2 require declaration before use (only a `POINTER`'s base type is
+exempt).  V3 rejecting them is **standard-conforming**.  They are listed
+for corpus-compatibility accounting, not as missing language features.
+
+`gap13` is the opposite case: `ORDL` is *not* a reserved word in Modula-2
+(`ORD`, `CHR`, `VAL`, … are predeclared identifiers, not keywords), so
+`PROCEDURE ORDL …` is legal standard M-2 and V3 is wrong to reject it.
+
 ## Not represented by a source
 
 - **Size-sensitive V3 miscompile** — a *latent* codegen bug that only