docs(rules): research-first rule, consult research repo and literature before guessing

AGENTS.md

@@ -16,6 +16,7 @@ For code changes, load at minimum:
 - `docs/rules/testing.md`
 - `docs/rules/verification.md`
 - `docs/rules/commits.md`
+- `docs/rules/research-first.md` (when stuck: read the research repo and the literature before guessing)
 
 ## What PureXML Is
 

CLAUDE.md

@@ -23,6 +23,7 @@ Non-negotiables:
 - `docs/rules/cross-platform.md`
 - `docs/rules/testing.md`
 - `docs/rules/verification.md`
+- `docs/rules/research-first.md` (when stuck: read `PureXML-research` sources and the literature before guessing; clean-room only)
 - `docs/production-readiness.md` (the bar for shipping this in an IDE; read every conformance iteration)
 
 Confirm rule loading with `rules-loaded`.

docs/rules/README.md

@@ -8,6 +8,7 @@ Load these rules before changing code:
 - `testing.md`
 - `verification.md`
 - `commits.md`
+- `research-first.md`
 
 Project-specific overrides:
 

docs/rules/research-first.md

@@ -0,0 +1,53 @@
+# Research first (when stuck, read the source and the literature)
+
+PureXML reimplements, in pure Swift, behavior that mature C/Java/C#/Python
+libraries already get right. When a spec point is ambiguous, an algorithm is
+unclear, a test disagrees with your reasoning, or you are about to guess: stop
+and consult sources before writing code. Guessing at a standard's corner case is
+how this engine accrues silent bugs. Reading the reference is how it stops.
+
+This is mandatory, in order:
+
+1. **Look in the research repo first.** The private `PureXML-research` repo
+   vendors reference implementations and analysis for exactly this purpose:
+   `libraries/` (libxml2, Xerces-J, Xerces-C, .NET `System.Xml.Schema`, Python
+   `xmlschema`, and others), `notes/` (prior clean-room write-ups), and the W3C
+   conformance suites. Find the matching routine and read it. The authoritative
+   algorithm is almost always already on disk. (Example: the MapAndSum
+   particle-restriction rule was fixed by reading Xerces `XSConstraints.java`,
+   after three incremental guesses had regressed ~30 cases.)
+
+2. **If the needed reference is not there, vendor it.** If no library in
+   `PureXML-research/libraries/` covers the area, add one (use the repo's
+   `scripts-vendor.sh` / vendoring convention). Pick a permissively licensed,
+   widely deployed implementation. Record it in the research repo's attribution.
+
+3. **If what is there is not enough, find more.** One implementation can be
+   wrong, stubbed, or lenient (libxml2 stubs particle-restriction; Microsoft and
+   Xerces disagree on spec-ambiguous points). When implementations disagree or
+   under-specify, gather more of them and compare; the W3C test metadata often
+   states which reading is intended.
+
+4. **Always consult the scientific and standards literature.** Read the W3C
+   Recommendation text itself (it is the spec, not a library's interpretation),
+   its errata, and the academic literature for the underlying algorithm
+   (content-model determinism / Glushkov and position automata, Brzozowski
+   derivatives, regular-language subset and ambiguity, schema composition). The
+   research repo's `references/` and `notes/` collect these; extend them.
+
+## Clean-room discipline (non-negotiable)
+
+The research sources are for **study, not copying**. PureXML stays pure Swift,
+dependency-free, Linux- and WASI-compatible (see `AGENTS.md`). Never copy C,
+Java, C#, JavaScript, or any non-Swift source into the public package. Extract
+the *algorithm and the invariants* from the reference, then implement them from
+first principles in Swift. Keep attribution accurate where compatibility work
+references a project.
+
+## What counts as "stuck"
+
+Not only a dead end. Any of: a corner case you cannot derive with certainty from
+the spec; a conformance test whose expected result contradicts your reasoning;
+an occurrence/namespace/derivation rule you are about to special-case by feel; a
+choice between two plausible interpretations. In all of these, the reference and
+the literature decide, not intuition. Disclose the source you used.