, #514)

Second wave of agent-friction documentation, plus a filed compiler
bug (#514) the agent surfaced during the same Game of Life run.

SKILL.md additions:
- **String escape sequences table**: full set (\\n, \\t, \\r, \\0, \\\\,
  \\", \\u{XXXX}).  Call out \\x / \\v / \\f etc. NOT supported, with
  two documented workarounds (unicode escape or
  string_from_char_code).  Confirms raw UTF-8 literals work
  ("██" compiles and prints).  Triggered by the agent trying \\x1b
  for an ANSI sequence and needing to discover string_from_char_code
  by inspection.
- **Nullary vs Unit-taking functions**: both `(-> T)` and `(@Unit -> T)`
  are valid; call sites must match the arity exactly.  Agent noticed
  both in the codebase and wondered which was "right".  Worked
  examples show both compile and run.
- **Stored function values and apply_fn**: the agent discovered
  apply_fn by inspecting prelude.py; it was never in SKILL.md.
  Added a subsection with a worked example and a pointer to
  examples/closures.vera and ch05_closures.vera for the full shape.
- **Known Bugs and Workarounds section** near the end of SKILL.md:
  new, dedicated table with the three classes of runtime bugs
  agents are most likely to hit — nested closures (#514), the 10
  pre-existing translator bugs (#475), and the 64 KB single-alloc
  limit (#487).  Each entry gives a shape, a concrete workaround,
  and the tracking issue.  Terminal sentence pins the diagnostic
  heuristic: "type-checks cleanly + mysterious runtime trap =
  probably #514 in a new shape."
- **Closure known-limitation subsection**: expanded to cover the
  two distinct failure modes (compile-time nested; runtime
  captured-scalar-through-indirection) with the agent's refined
  isolation matrix (see #514 comment).

Non-SKILL updates:
- KNOWN_ISSUES.md: new #514 row under Bugs covering both failure
  modes and the workaround.
- scripts/check_skill_examples.py: clean allowlist rewrite, 66
  unique entries, AST-verified zero duplicate keys.  The previous
  state had 7 duplicate keys from fix_allowlists shifting entries
  into collision — memory feedback_spec_allowlist.md covers this
  failure mode.

Full validation green: 54 parsed + 66 allowlisted = 120 SKILL.md
blocks handled, 0 failures; doc counts consistent; site assets
up-to-date; 19 doc-related tests pass.

Co-Authored-By: Claude <noreply@anthropic.invalid>

Two new issues surfaced by the same agent run:

- #515: $gc_collect itself faults with out-of-bounds memory access
  under sustained allocation pressure.  40×20 Conway's Game of Life
  over 200 generations reliably reproduces.  The collector walks
  past $heap_ptr to the linear-memory bound and traps — gc_collect
  is the top frame of the crashing stack, not the program.  This
  is distinct from #487 (alloc path) and #484 (sweeper 16-bit
  truncation).
- #516: Runtime traps bubble up as raw wasmtime stack traces; the
  CLI mis-labels every Trap/WasmtimeError as "Runtime contract
  violation" even when the actual cause is out-of-bounds memory
  access, integer overflow, unreachable, etc.  No source-line
  mapping, no actionable guidance — the exact opposite of the
  carefully crafted compile-time diagnostics.  Three-stage
  proposed scope: categorise trap reason, source-map the Vera
  function that trapped, specialise help for common trap classes.

KNOWN_ISSUES.md updated with rows for both.

ROADMAP.md implementation-order table re-sorted:
  1. #514 (nested closures + captured-scalar indirection)
  2. #515 (GC collect faults)
  3. #516 (runtime trap diagnostics)
  4. #475 (WASM translator bug cleanup — previously #1)
  5. #507 (Eq/Ord-dispatched array ops)

The top three are all surfaced by the single Game of Life agent
run — the empirical signal is the clearest prioritisation we've
had.  #475 was promoted to #1 after PR #511 merged; pushed to #4
as the new issues outrank it on agent-adoption impact.

Agent-noted quote, worth capturing as the motivation for #516
specifically:

  "the gap between 'the type system is happy' and 'the compiled
   artefact actually runs' is wider than you'd expect from a
   language with SMT-verified contracts. The verifier can prove
   your termination argument is sound while the codegen silently
   miscompiles your closure environment out from under you."

Also posted comment on #514 documenting the third shape the
agent is now isolating (closure body with i32/i64 type mismatch,
distinct from direct-nesting and captured-scalar-indirection).

No code changes.

Co-Authored-By: Claude <noreply@anthropic.invalid>

Fourth round of agent isolation has narrowed #514 from "nested
closures" + "captured scalar through array_map" to a single root
cause:

**Closures can capture primitive outer bindings (Int, Nat, Bool,
Byte, Float64) but NOT heap-allocated ones (String, Array<T>, any
ADT, opaque handles).**

The previously documented shapes were narrow manifestations of the
same bug.  vera check and vera compile both succeed for heap-
capture shapes; vera run fails with "unknown table 0" or
"i32/i64 type mismatch" at WASM validation.

Changes:
- SKILL.md "Capturing outer bindings" rewritten to lead with the
  limitation, enumerate which types work and which don't, and
  point at the recursion-with-explicit-parameters workaround.  A
  new "What you cannot capture" subsection lists every heap type.
  A "Workaround: tail recursion with explicit parameters"
  subsection shows the lifted-function pattern that dodges the
  bug (demonstrated end-to-end in examples/life.vera once that
  example lands).
- KNOWN_ISSUES.md #514 row rewritten with the sharpened root
  cause, the full list of failing capture types, the primitive-
  capture allowlist, and the two observed validation error
  shapes.
- #514 on the issue tracker updated with the fourth-round
  isolation matrix and an investigation pointer at
  vera/wasm/closures.py._compile_lifted_closure's environment
  struct emission (my hypothesis: environment field layout
  treats all captures as i64 scalars, fine for primitives, wrong
  for pair-shaped or ADT values).
- scripts/check_skill_examples.py allowlist regenerated via
  fix_allowlists, then manually de-duplicated (two line-number
  collisions from the shift) and extended with 3 new FRAGMENT
  entries for the BROKEN-example blocks in the updated closure
  section.  AST-verified 68 unique keys, 0 dups.

Ready to ship as the first commit of the docs-only PR (#513).
More signals can land as additional commits before merge if the
agent run surfaces further gaps.

Co-Authored-By: Claude <noreply@anthropic.invalid>

CodeRabbit caught two copies of the same BROKEN/WORKING nested-closure
example pair — one labeled (1) and one unlabeled but otherwise identical.
Dropped the unlabeled duplicate; kept the (1)-labeled copy as the
canonical example for the 'Known limitation: nested closures and
captured-scalar indirection' subsection.

scripts/check_skill_examples.py: cleaned up ALLOWLIST (fix_allowlists
re-introduced duplicate keys per the memory'd bug; manually deduped
and re-verified 66 unique entries, 0 duplicates).

Co-Authored-By: Claude <noreply@anthropic.invalid>