feat: add planning and Polars GFQL skills

[lmeyerov]

Summary

• Slim the maintainer-only internal/plan skill and add a maintainer-only internal/review skill. Both stay internal (metadata.internal: true); neither ships in the public tier.
• Document GFQL execution engines: explicit polars / polars-gpu selection, result frame types, the exact engine literals, off-engine analytic bridging, and GPU-or-error semantics.
• Grow pygraphistry_gfql_polars_engines_v1 to 7 cases so it measures skill lift rather than recognition.

Why

PyGraphistry gained Polars CPU and Polars-GPU execution, but the skills did not explain the explicit opt-in, the output frame types, or safe handling of off-engine analytics.

Verified against the implementation, not the docs

Every claim was checked by running it — first against a pygraphistry 0.57.0+173 checkout while drafting, then re-verified against the released 0.58.0 so the guidance is true for users installing from PyPI:

behavior	observed
engine='auto' on a Polars input graph	returns pandas.DataFrame
engine='polars'	returns polars.DataFrame
engine='polars-gpu' without RAPIDS	ImportError: ... requires the RAPIDS cudf_polars stack ... or use engine='polars'
hypergraph(..., engine='polars')	AttributeError: 'ValueError' object has no attribute 'copy'
strict analytic policy	graphistry.compute.gfql.lazy.set_call_mode, env GFQL_POLARS_CALL_MODE

Consequently the skills do not recommend hypergraph(..., engine='polars'|'polars-gpu'): the type annotation lists both engines, but graphistry/hyper_dask.py has no dispatch, so the call fails at runtime. Filed upstream as graphistry/pygraphistry#1775.

Evals

The two original cases both scored 1.0 with skills off, i.e. they tested recognition, not skill lift. Five cases were added that a skills-off baseline can plausibly fail:

• polars_functional_native_roundtrip — functional: builds Polars frames and asserts type(result._nodes).__module__ is polars. Deterministic checks bar import pandas / pd.DataFrame(; the oracle rubric carries "no pandas conversion anywhere".
• polars_auto_engine_regression — Polars in, pandas out; the fix must be engine selection, not a conversion back.
• polars_strict_call_mode_benchmark_integrity — requires the graphistry.compute.gfql.lazy import path, the env-var equivalent, and NotImplementedError handling.
• hypergraph_polars_engine_refusal — the stale-annotation trap above.
• polars_gpu_availability_fallback_ownership — the application owns the fallback; PyGraphistry does not fall back silently.

A response during evaluation hallucinated engine="polars_gpu" (underscore) and a nonexistent strict=True kwarg, so the skills now state the exact engine literals and that gfql() has no strict= argument.

Eval results

Benchmarked against a pristine, write-protected graphistry==0.58.0, with a SHA-256 baseline over the installed package verified identical after the run, under hybrid grading (--grading hybrid --oracle-harness claude). Baseline isolation verified.

	Skills ON	Skills OFF
Pass rate	6/7 (85.7%)	6/7 (85.7%)
Avg score	0.94	0.92
Avg latency	70.3s	102.1s

No pass-rate delta. The measurable difference is latency — skills reached the same answers ~1.45x faster. Both arms fail the same case. The pack is checked in as a regression harness for the Polars/Polars-GPU surface, and README/benchmarks/README.md/CHANGELOG say so rather than citing it as an improvement.

A retraction, and why it matters

An earlier version of this PR published +28.6pp for this pack. That result was invalid and has been retracted. An agent under evaluation edited the installed library inside the eval venv — graphistry/Engine.py, resolve_engine's polars branch, Engine.PANDAS → Engine.POLARS — at 07:21 UTC, and every published row ran at 07:41 UTC or later. The case driving the delta, polars_auto_engine_regression, asks why a result came back as pandas without an explicit engine; the patch invalidated that premise, so the baseline failed for an environmental reason. In a clean environment that same baseline cell passes (0.90).

Two harness lessons are now documented in DEVELOP.md:

• Verify the environment, don't assume it. Agents under test share a writable environment with the benchmark. Take a checksum before the sweep, re-verify after, discard the run if it moved. A pack that names a package version is making an environment claim.
• Grade judgment cases with rubrics. Deterministic regex repeatedly failed substantively correct answers (a program written to a file rather than inlined; "0.83x (slower)" instead of "can be slower"; "zero Polars branches" instead of "no dispatch"), inflating apparent lift.

What does still discriminate

In a separate hybrid run of the perf/tuning cases, the one case where the baseline substantively failed was polars_parity_or_decline_no_fake_fallback (oracle 0.55 vs 0.94 with skills): asked to build a wrapper that keeps reporting engine='polars' while quietly running pandas, the baseline complied. With a package it can read, a strong baseline recovers API facts on its own — integrity and judgment content differentiates; API recall does not.

Not covered

• codex half did not run. Usage credits exhausted for the window; every cell returned You've hit your usage limit, produced no model output, and is discarded rather than scored.

Validation

• python3 scripts/ci/validate_skills.py — 13 skill directories OK.
• python3 scripts/ci/validate_release.py --pr — OK, 0 warnings.
• ./bin/evals/claude-skills-smoke.sh — exit 0, all six pygraphistry skills discovered.
• ./bin/evals/codex-skills-smoke.sh — not run, blocked by the same Codex usage limit.
• scripts/evals/gfql_functional_check.py executes the generated code against pygraphistry and passes.
• Journey JSON parses; all regex / must_not_regex patterns compile.