MagicAST: write CONTRIBUTING.md terminology + AST styling guide; auto-generate GLOSSARY.md

[Spelkington]

Parent

Follow-up to the MagicAST restructure milestone. Depends on all five restructure phases (#2–#6) so the documented conventions describe the post-restructure architecture, not the current one.

What to build

Two related deliverables:

1. CONTRIBUTING.md terminology + AST styling guide

Expand libs/magic-ast/CONTRIBUTING.md to be the canonical reference for contributors and AFK agents working on MagicAST. Two new sections at the bottom of the file:

AST styling conventions:

• File organization (where new ability/effect/parser files go, how to pick a directory under AST/)
• Naming conventions (discriminator string format, class name format, record field naming)
• The attribute-driven registration pattern ([OracleAbility], [OracleEffect], [OracleAbilityParser], [StructuralKeyword]) — examples and gotchas
• Trait interface conventions (IOptionalEffect, IDurativeEffect, etc.) — when to declare a new trait vs. reuse an existing one
• Diagnostic conventions: when to emit an UnparsedAbility, how to choose a Diagnostic.Pattern string, when to extend FallbackParser.InferFailurePattern

Terminology (glossary):
The grilling session that produced this milestone resolved a set of terms that should be documented authoritatively. Starting list, not exhaustive:

• TDD loop — the per-card round-trip cycle (hand-parse JSON → schema-gap red → parser-gap red → green)
• Schema gap (Red Feat/atlas api web #1) — JsonException at deserialization because the AST type system can't represent the hand-parsed JSON (missing node type / missing field / unknown discriminator)
• Parser gap (Red MagicAST restructure: Phase 1 — Data-driven structural-keyword table #2) — OracleParser output doesn't match the hand-parsed expected output even though both are representable
• Hand-parsed card — a JSON file under HandParsedCards/{set}/{name}.json containing input (CardInputDTO) + output (expected CardOutputAST)
• Triage — Flowthru pipeline that runs the parser over the full Scryfall oracle corpus, aggregates failure patterns by frequency, and emits a ranked report
• Triage report — Data/_08_Reporting/triage-report.json, the artifact agents read to pick their next assignment
• Ratchet baseline — test-baseline.json, the snapshot of which tests are currently passing/failing; CI fails on regressions but tolerates stable failures
• Cleanliness score — per-oracle-line metric ranking how well-isolated a candidate exemplar is for a target pattern (definition TBD — pending decision in the same session)
• Oracle line — a \n-split chunk of a card's oracle text; the unit used by OracleLineTests
• Card coverage / line coverage — the two completeness metrics in the triage report (card-level = all abilities parse; line-level = % of lines parsed)

The styling section should reference the auto-generated GLOSSARY.md (deliverable 2 below) as the source of truth for the current set of AST nodes.

2. Auto-generated GLOSSARY.md

A script under libs/magic-ast/scripts/ (suggested: generate-glossary.sh or a small C# tool) that:

• Walks libs/magic-ast/AST/**/*.cs
• Extracts <summary> XML doc comments paired with their immediately-following class/record declarations
• Groups results by directory (e.g., Effects/Damage/* becomes a section)
• Emits libs/magic-ast/GLOSSARY.md at the root of the library

No Roslyn, no DocFX — straight text/regex parsing is fine. The script runs on demand (during the agent loop, before the agent hand-parses) and as part of CI (to detect undocumented additions).

Acceptance criteria

Part 1 (CONTRIBUTING.md)

• libs/magic-ast/CONTRIBUTING.md has an "AST styling" section covering file org, naming, attribute usage, trait conventions, diagnostic conventions.
• libs/magic-ast/CONTRIBUTING.md has a "Terminology" / "Glossary" section at the bottom covering the terms listed above plus any others surfaced during writing.
• The styling section references GLOSSARY.md as the live source of current AST node types.
• Cross-references back to the relevant restructure issues (MagicAST restructure: Phase 1 — Data-driven structural-keyword table #2–MagicAST restructure: Phase 5 — Optional DTO layer for AST/JSON decoupling #6) for the why behind the patterns.

Part 2 (GLOSSARY.md script)

• Script under libs/magic-ast/scripts/ produces libs/magic-ast/GLOSSARY.md from XML doc comments.
• Output is grouped by AST subdirectory (Abilities, Effects/Damage, Effects/Counter, etc.).
• Each entry shows: type name, discriminator string (from [OracleAbility] / [OracleEffect] attribute), summary text, and source file link.
• CI fails if GLOSSARY.md is out of date relative to the source (i.e., script is part of pre-commit or CI; not just on-demand).

Blocked by

• MagicAST restructure: Phase 1 — Data-driven structural-keyword table #2 (Phase 1 — [StructuralKeyword] pattern documented)
• MagicAST restructure: Phase 2 — JSON polymorphic converter via attribute scan #3 (Phase 2 — [OracleAbility] / [OracleEffect] patterns documented)
• MagicAST restructure: Phase 3 — Parser dispatch via attribute scan #4 (Phase 3 — [OracleAbilityParser] pattern documented)
• MagicAST restructure: Phase 4 — Trait composition for Effect #5 (Phase 4 — trait interface conventions documented)
• MagicAST restructure: Phase 5 — Optional DTO layer for AST/JSON decoupling #6 (Phase 5 — final DTO layer decision reflected in the styling guide)

[Spelkington]

Cleanliness score definition locked (2026-05-24 grilling session): Definition D — P-purity ratio.

score(L, P) = 1 − (count of P-diagnostics in L) / (total diagnostics in L)

• Lower = better (cleaner exemplar).
• score = 0 → 100% of failures on this line are pattern P (ideal isolated exemplar).
• score = 0.7 → P accounts for 30% of failures on this line.
• Normalized to [0, 1], scale-invariant across line lengths.
• lineLength asc remains the secondary tiebreaker.

Update the terminology section to use this definition verbatim when this issue is actioned. Definition E (span-isolation) was considered and deferred — gated on a future Diagnostic.Location accuracy audit.