Add semantic context lanes and cross-language artifacts

[wolfiesch]

Summary

This PR lands the ExcelBench context-lane sprint as one dependency stack:

• adds optional external oracle/helper infrastructure for Excelize, LibreOffice, ClosedXML, NPOI, ExcelJS, and Apache POI fixture work
• adds workbook semantic snapshot/diff tooling, richer failure explanations, roundtrip/idempotence, compatibility, chart, and macro context lanes
• promotes Apache POI and Excelize into cross-language context adapters with focused tests
• publishes dated release, cross-language, and pivot capability artifacts with README/methodology/reporting guidance

Review Guide

Suggested review chunks:

1. External oracle foundation and fixture helper specs
2. Semantic diff/context-lane infrastructure
3. Cross-language adapters plus checked-in evidence artifacts

Verification

• uv run ruff check src/excelbench tests
• uv run mypy
• uv run pytest -q (1230 passed, 52 skipped, 6 xfailed)

Notes

• Context lanes are additive evidence artifacts; they do not change the main fidelity scoring model.
• Cross-language outputs are intentionally labeled as ecosystem context, not Python replacement rankings.
• Pivot evidence is separate because the shipped macOS pivot fixture remains non-scoreable.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 97903cb505

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[Copilot]

Pull request overview

This PR introduces “context lanes” and cross-language evidence tooling for ExcelBench by adding optional external-oracle helpers (Go/Java/.NET/Node/LibreOffice), semantic workbook snapshot/diff infrastructure, richer failure explanations in rendered reports, and checked-in dated artifact outputs for release + cross-language context.

Changes:

• Add optional external oracle helpers (LibreOffice, ExcelJS, NPOI, ClosedXML, Apache POI, Excelize) plus fixture-pack specs and generation/validation scripts.
• Add semantic workbook snapshot + diff tooling and new context-lane runners (roundtrip/idempotence + artifact context).
• Enrich results rendering with structured failure explanations and a generated WHY_FAILED.md output when failures exist.

Reviewed changes

Copilot reviewed 80 out of 88 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tools/external-oracles/npoi/npoi-oracle.csproj	Adds NPOI .NET external-oracle project definition.
tools/external-oracles/npoi/README.md	Documents how to run the NPOI oracle and supported operations.
tools/external-oracles/npoi/Program.cs	Implements NPOI oracle JSON contract for fixture writing + metadata reads.
tools/external-oracles/libreoffice/libreoffice_oracle.py	Adds LibreOffice headless conversion/validation helper.
tools/external-oracles/libreoffice/README.md	Documents LibreOffice oracle usage and operations.
tools/external-oracles/exceljs/package.json	Adds Node oracle package definition and pinned deps.
tools/external-oracles/exceljs/exceljs-oracle.cjs	Implements ExcelJS oracle JSON contract for fixture writing + metadata reads.
tools/external-oracles/exceljs/README.md	Documents ExcelJS oracle usage and supported operations.
tools/external-oracles/excelize/main_test.go	Adds smoke test asserting Excelize helper emits expected advanced OOXML parts.
tools/external-oracles/excelize/go.sum	Adds pinned Go dependency checksums for Excelize helper.
tools/external-oracles/excelize/go.mod	Adds Go module definition for Excelize helper.
tools/external-oracles/excelize/README.md	Documents Excelize oracle usage and payload keys.
tools/external-oracles/closedxml/closedxml-oracle.csproj	Adds ClosedXML .NET external-oracle project definition.
tools/external-oracles/closedxml/README.md	Documents ClosedXML oracle usage and supported operations.
tools/external-oracles/apache-poi/fetch_deps.py	Adds script to fetch/verify pinned POI jars from Maven Central.
tools/external-oracles/apache-poi/build.sh	Adds local bootstrap script to fetch deps, compile, and self-test POI helper.
tools/external-oracles/apache-poi/README.md	Documents Apache POI oracle bootstrap and supported operations.
tests/test_semantic_diff.py	Adds unit tests for snapshot + semantic diff + artifact writing.
tests/test_failure_explainer.py	Adds tests for diagnostic/failure classification logic.
tests/test_external_fixture_pack.py	Adds tests for external fixture specs stability and pack generation/validation behavior.
tests/test_cross_language_context_cli.py	Adds CLI tests for cross-language context output generation.
tests/test_context_lanes.py	Adds CLI tests for diff-workbooks, roundtrip, compatibility skip, and macro-context skip behavior.
src/excelbench/results/renderer.py	Enriches rendered outputs with explanations and writes WHY_FAILED.md on failures.
src/excelbench/results/failure_explainer.py	Adds failure explanation classifier and renderer for “why failed” reporting.
src/excelbench/models.py	Extends Diagnostic with root-cause code and suggested next-step fields.
src/excelbench/harness/workbook_snapshot.py	Adds deterministic semantic snapshot extraction (cells/formats/parts/etc).
src/excelbench/harness/semantic_diff.py	Adds snapshot comparison + diff artifact writer + markdown renderer.
src/excelbench/harness/roundtrip_runner.py	Adds roundtrip/idempotence context lane runner using semantic diffs.
src/excelbench/harness/external_oracles.py	Adds subprocess JSON contract + tool catalog for optional external oracles.
src/excelbench/harness/external_fixture_specs/npoi.py	Defines NPOI external fixture spec + expected package parts + readback probes.
src/excelbench/harness/external_fixture_specs/exceljs.py	Defines ExcelJS external fixture spec + expected package parts + readback probes.
src/excelbench/harness/external_fixture_specs/excelize.py	Defines Excelize external fixture specs for pivot/slicer/chart/CF and chart-points cases.
src/excelbench/harness/external_fixture_specs/closedxml.py	Defines ClosedXML external fixture specs for pivot/CF/table and rich-comment/protection cases.
src/excelbench/harness/external_fixture_specs/base.py	Adds shared ExternalFixtureSpec dataclass for fixture-pack definitions.
src/excelbench/harness/external_fixture_specs/apache_poi.py	Defines Apache POI external fixture spec + expected parts + readback probes.
src/excelbench/harness/external_fixture_specs/init.py	Exposes all external fixture specs and aggregates them into one list.
src/excelbench/harness/external_fixture_pack.py	Adds generator to create fixture packs via oracles + optional LibreOffice validations.
src/excelbench/harness/artifact_context.py	Adds chart + macro artifact context lanes and output renderers.
src/excelbench/harness/adapters/wolfxl_adapter.py	Updates WolfXL adapter for new writer backend naming and adds image read/write behavior.
src/excelbench/harness/adapters/excelize_adapter.py	Adds write-only adapter backed by Excelize external helper.
src/excelbench/harness/adapters/apache_poi_adapter.py	Adds write-only adapter backed by Apache POI external helper.
src/excelbench/harness/adapters/init.py	Registers new cross-language adapters behind availability checks.
scripts/validate_external_oracle_fixtures_with_wolfxl.py	Adds CLI script to validate external fixtures via WolfXL modify-save + probes.
scripts/generate_external_oracle_fixtures.py	Adds CLI script to generate external fixtures and optionally run LibreOffice validators.
results-release-2026-04-28/matrix.csv	Adds checked-in release snapshot artifact (matrix).
results-release-2026-04-28/history.jsonl	Adds checked-in release snapshot artifact (history entry).
results-release-2026-04-28/FIDELITY_DELTAS.md	Adds checked-in release snapshot artifact (deltas stub).
results-release-2026-04-28/DASHBOARD.md	Adds checked-in release snapshot artifact (dashboard).
results-cross-language/matrix.csv	Adds checked-in cross-language context artifact (matrix).
results-cross-language/history.jsonl	Adds checked-in cross-language context artifact (history entry).
results-cross-language/README.md	Adds checked-in cross-language context artifact (rendered report).
results-cross-language/FIDELITY_DELTAS.md	Adds checked-in cross-language context artifact (deltas stub).
results-cross-language/CONTEXT.md	Adds checked-in cross-language context artifact (framing/guardrails).
results-cross-language-pivots/results.json	Adds checked-in pivot capability artifact (raw JSON).
results-cross-language-pivots/README.md	Adds checked-in pivot capability artifact (report).
results-cross-language-pivots/CONTEXT.md	Adds checked-in pivot capability artifact (framing note).
docs/trackers/excelize-adapter-design.md	Adds design doc for Excelize adapter scope/rollout.
docs/trackers/cross-language-comparison-strategy.md	Adds strategy doc for separating Python vs cross-language lanes.
docs/trackers/apache-poi-excelize-rollout-plan.md	Adds rollout plan for first cross-language context adapters.
docs/trackers/apache-poi-adapter-design.md	Adds design doc for Apache POI adapter scope/rollout.
docs/public-reporting.md	Adds public reporting policy and artifact citation guidance.
docs/cross-language-context.md	Adds explainer doc for cross-language context lane and how to cite it.
decisions.md	Records decisions for semantic diff/context lanes and external oracle contract.
architecture.md	Updates architecture overview to include semantic diff + external oracles layer.
METHODOLOGY.md	Updates methodology to reflect cross-language context support and latest snapshot framing.
LAUNCH.md	Adds launch messaging draft and claim guardrails.
.gitignore	Ignores external oracle build outputs and local results directories.

Files not reviewed (1)

• tools/external-oracles/exceljs/package-lock.json: Language not supported

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.