diff --git a/AGENTS.md b/AGENTS.md index 1c21f90..9af54e6 100644 --- a/AGENTS.md +++ b/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 diff --git a/CLAUDE.md b/CLAUDE.md index 17ea177..7e9e426 100644 --- a/CLAUDE.md +++ b/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`. diff --git a/docs/rules/README.md b/docs/rules/README.md index 654b24c..91aa448 100644 --- a/docs/rules/README.md +++ b/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: diff --git a/docs/rules/research-first.md b/docs/rules/research-first.md new file mode 100644 index 0000000..e7458d0 --- /dev/null +++ b/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.