Restructure PARCE: foundations, conventions, CI, and an ontology-grounded plan

[mengerj]

What & why

Sets the foundation for repointing PARCE from an LLM narrative writer to a deterministic, ontology-grounded multi-source harvester whose only LLM use is structured extraction from messy metadata. No production code behavior changes yet — this PR lands the plan, conventions, tooling, and a CI fix so the refactor PRs (2–8) have a clean, green baseline to branch from.

Contents

Planning & conventions

• docs/ARCHITECTURE.md — design source-of-truth: design-vs-outcome principle (why cell type is excluded as context), the modality/structure source gradient (CELLxGENE → GEO → PRIDE), the adapter → normalizer → ontology → graph pipeline, the target canonical schema, and §5 Ontology grounding: facet→ontology registry (EFO/UBERON/MONDO/NCBITaxon/ChEBI/PSI-MS/EDAM) and the rule that "modality" is two controlled fields — an EFO assay term + a coarse molecular_layer enum derived by walking EFO is-a ancestors.
• CLAUDE.md — working conventions: where the LLM is allowed to live, layout, dependency direction, quality gates, and the per-session working agreement (incl. the unit-test hermeticity rule).
• docs/ROADMAP.md — living plan with a ▶ Next up marker, an 8-PR sequence, backlog, and a Session Log that each session updates for the next.

Tooling / CI

• .github/workflows/ci.yml — uv-based, Python 3.11 + 3.13 matrix: ruff check, ruff format --check, mypy src/parce, unit pytest (integration excluded).
• pyproject.toml — expanded ruff rules (E,F,I,UP,B,SIM,C4,RUF), mypy + pydantic plugin, mypy added to dev deps; uv.lock refreshed.
• Formatted existing code + two small lint fixes so CI is green from the first commit.

Fixes

• Made TestRunOrchestration hermetic — it constructed Settings() (required AZURE_AI_PROJECT_ENDPOINT, no default) and only passed locally via a dev .env; CI (no .env) failed. Patched Settings via an autouse fixture.
• Bumped CI actions to checkout@v5 / setup-uv@v6 (Node 20 deprecation).

Reviewer notes

• mypy is green by temporarily exempting parce.tools.* and parce.agent.* (the IO modules slated for rewrite). Documented in pyproject.toml + roadmap; each future PR removes a module's exemption as it migrates — no new exemptions.
• Specific ontology term IDs are intentionally not hardcoded — the registry pins ontologies, term IDs are resolved at runtime via OLS4 (decided in PR 4).
• main.py still runs the old narrative pipeline; it is removed in PR 3.

Verification

All four gates pass on both Python 3.11 and 3.13 in CI. Unit tests verified hermetic by running with .env moved aside (reproduces the runner).