# docs/ index

`docs/` has accumulated many per-session records.  This index points to
the **load-bearing** documents; everything else is history (useful for
bisecting *why* a decision was made, not for reading end-to-end).

## Start here

- **`handoff-2026-10-19-next.md`** — next-session plan (P1–P5 status,
  the ASTDUMP root cause, gates).
- **`STATUS.md`** — current state, architecture, conformance policy,
  what remains.
- **`plan.md`** — the phased plan (Blaise-adapted).
- **`features.md`** — the feature list.
- **`analysis_gaps.md`** — language gaps + corpus notes.
- **`gaps/README.md`** — minimal reproducers, one per unsupported gap,
  and the gm2-extension policy.

## Designs / running records

- `analysis_generics.md` — generics (chosen ISO 10514-2 form, mechanism,
  increments).
- `plan-two-phase.md`, `plan-two-phase-parse.md` — the AST/`Lower` split
  and the two-phase (deferred-body) parse.
- `plan-resolve-check.md` — the resolve/check thread (now concluded; the
  pass was deleted).
- `plan-lower.md` — the `Lower` emitter.
- `blaise-phases-map.md`, `language-report.md`, `grammar.md` — the
  grammar/phases reference.
- `summary_l3_selfhost_fix.md` — the self-host root cause; also where
  the "size-sensitive miscompile" is root-caused (2026-10-19).

## Recent session summaries (newest first)

- **2026-10-19 (P0–P4):** generics double-instantiation fixed (lower each
  unit in its own scope); `__FILE__`/`__LINE__`; scalar→`ARRAY OF BYTE`;
  P2 gm2 extensions (VAR same-size, bare proc value, variant records,
  set `CASE`); strict body declaration order (data); the "size-sensitive
  miscompile" root-caused (it was the fixpoint gate).  See `STATUS.md`
  and `handoff-2026-10-19-next.md`.
- `summary_corpus-sweep-2026-10-18.md` — corpus sweep (builtins, bool/enum
  bounds, set-of-enum, forward set); set-constant + folding findings.
- `summary_set-constants-2026-10-18.md` — SET CONST (static masks,
  folded unions), builtin CONST folding (CAP/ABS/ODD, BOOLEAN consts),
  CONST representation conversions, forward array-index types,
  procedure values, SYSTEM sized reals, builtin imports (SHIFT), and
  ISO foreign modules.
- `summary_dlist-showcase-2026-10-16.md` — showcase23 + limitation fixes.
- `summary_generics-limitations-fixed-2026-10-16.md` — the two
  template/proc-param limitations, fixed.
- `summary_showcase23-dlist-2026-10-16.md` — the DList showcase + the
  global-record data-size bug.
- `summary_generics-closed-2026-10-16.md` — generics: what works, what
  does not (generic classes: via generic modules; dedup: N/A).
- `summary_generics-inc3-2026-10-16.md` — value params, kind
  constraints, proc params, constraint model.
- `summary_two-phase-complete-2026-10-16.md` — two-phase complete,
  `Check` removed.

Everything else (`summary_stepN.md`, `summary_two-phase-sliceN.md`,
`summary_<topic>.md`, `session-*.md`, `session-handoff-*.md`) is a
chronological record kept for provenance.  The ones nobody references —
and that reference no other doc — have been collected under
`docs/archive/`; the remainder (still linked from somewhere, or linking
to the load-bearing docs) stay in `docs/`.