PureXML/GEMINI.md

GEMINI.md, always-on rules for Antigravity agents in PureXML

These rules are always in effect. The full, step-by-step procedure is in docs/onboarding-antigravity.md, read it before your first change. When a rule here and a guideline elsewhere conflict, this file wins.

The prime directive

PureXML is an XML/XSD validator. Never reject a valid schema or a valid document. In the conformance counts this is valid-schemas-rejected; it is 1 and must never rise. Under-rejecting (missing an invalid schema) is acceptable; over-rejecting (rejecting a valid one) is a failure and must not be merged. When unsure, do less.

Hard constraints (never violate)

• No external SwiftPM dependencies. No C/C++/Objective-C/JavaScript/generated runtime. Pure Swift only.
• Public API stays under the PureXML namespace tree.
• Must build on macOS, Linux, and WASI.
• Reference implementations are for reading only, never copying (clean-room).
• Tests import only Foundation, Testing, and @testable import PureXML.

Per-change procedure (do every step; details in the onboarding doc §6)

1. Measure first: read /tmp/xsts-failures.txt, pick a family, read the actual .xsd files before coding. Do one rule per change.
2. Implement conservatively in Sources/Schema/; return [String] errors; wire into an aggregator in SchemaIDAttribute.swift.
3. Add unit tests (one rejected case + several accepted cases). Write the test file before launching the release XSTS run.
4. Run all gates (build, swiftformat --lint, swiftlint --strict, check-style.sh, check-namespacing.sh, swift test, check-wasm.sh).
5. Run the conformance differential: XSTS_ROOT=/private/tmp/xsts/xmlschema2006-11-06 swift test -c release --filter XSTS. invalid-schemas-accepted must go DOWN and no other bucket may rise.
6. Run an adversarial critic that tries to construct a valid schema your change rejects. Fix any false positive before merging. (Mandatory.)
7. Update the pinned baseline in Tests/XSTSSuiteTests.swift, add a CHANGELOG.md entry, update docs/schema-validity-burndown.md.
8. Branch off main, commit, git merge --ff-only, push to GitHub.

The traps that recur (onboarding doc §8)

• Namespace conflation: resolve a name's namespace with XSDNode.referenceNamespace(ref, bindings); never just strip the prefix. A built-in (xs:*) or imported component must not be confused with a same-local-name user one. This has caused false positives 7+ times.
• swiftformat vs swiftlint brace conflict: extract a multi-condition if into a Bool helper; turn a long for ... where into guard ... continue.
• Limits: file ≤ 400 lines, type body ≤ 250, cyclomatic ≤ 10, params ≤ 5, line ≤ 180. Split into new files/helpers; bundle args into a labeled tuple.
• Read schema attributes unprefixed (prefix == nil); skip foreign-namespace nodes and xs:appinfo/xs:documentation.

Commit discipline (never violate)

• Commit format: type(scope): summary. No em dashes anywhere.
• No AI attribution of any kind in commits, PRs, branches, code, or docs (no "Generated with", no "Co-Authored-By", no mention of Gemini/AI/agent). All work reads as human-authored. (docs/onboarding-antigravity.md is the sole exception, explicitly requested.)
• Never push to a GitLab remote. GitHub remotes only; check the URL first.
• Merge to main --ff-only. The pre-push hook runs swift test and a commit-message check.

Definition of done

All gates green; conformance differential shows invalid-accepted down and no other bucket up (valid-rejected still 1); the critic found zero false positives; baseline/CHANGELOG/burndown updated. If you rejected even one valid schema, the change is wrong regardless of how many invalid ones it caught.