feat: complete Panel Tier-1 Stage C covariance

[TheHiddenObserver]

Scope

Tracks #93 and implements Panel Tier-1 Stage C / covariance completion on top of merged Stage B (#122).

Reviewed plan:

dev/plans/panel_p1_stage_c_covariance_plan.md

Current acceptance status — COMPLETE

Exact final candidate head:

e16df4c966c3230edcf921cf18d23f583cb05aa1

Fresh exact-final .claude/skills/code-review.md review: 4893480429.

• CRITICAL: 0
• HIGH: 0
• relevant MEDIUM: 0
• unresolved review threads: 0
• temporary lifecycle workflows/helpers: 0

Stage C includes HC0/HC2/HC3 while preserving historical robust=HC1, one-/two-way clustering with opt-in group debiasing, Driscoll-Kraay Bartlett/Parzen/QS, RandomEffects covariance on its quasi-demeaned GLS fit space, five residual-OLS estimator integrations, public covariance primitive backend auto-detection, maintained Torch CPU coverage, pinned external alignment, and separate physical correctness/performance runners.

Physical GPU acceptance

Exact clean measurement SHA:

9c0b3050dd143c43a06bb6393d69f4f83e861637

Immutable artifact repository commit:

85d710bddf633134624501a9e27f03c30bc04ead

Tesla P100 correctness passed for both GPU backends:

• CuPy: 26/26 estimator covariance cases + 2/2 direct public primitives
• Torch: 26/26 estimator covariance cases + 2/2 direct public primitives
• requested/executed backend identity verified; no CPU fallback

Canonical physical-validation source:

• source ID: panel-stage-c-validation-pr126-20260810-a0d258f6d6b8
• raw path: results/pr126_p100/panel_stage_c_gpu_validation_9c0b3050.json
• SHA-256: a0d258f6d6b8243e82684a29305606e5f6bd91bbe271c3ed335b32b5ec973665
• Git blob: fe015f03fd488e22d40beccfe4cbe1984b25f5b7
• 56 validation-only canonical rows; no timing/speedup claim

Canonical synchronized-performance source:

• source ID: panel-stage-c-performance-pr126-20260810-214284f02a5e
• raw path: results/pr126_p100/panel_stage_c_performance_9c0b3050.json
• SHA-256: 214284f02a5e21e775e58deaf2fa3cc9b6384d392b96c6f300f31f4a02953b1c
• Git blob: 53a06d82764bdeeb962eda5096fb6ee79220d5b0
• 58 synchronized timing rows = 54 base + 4 explicit high-T QS rows
• high-T scenario: N=10,000, k=2, T=200
• no speedup or CPU-baseline claim

The canonical performance parser uses T-specific scale identities (..._t20 and ..._t200) and fails closed on the exact base and high-T backend/case matrices.

Physical-evidence applicability

Comparing measurement 9c0b3050... to final head e16df4c... shows only evidence, parser/manifest/catalog/coverage, tests, generated assets, changelogs/review record, and permanent benchmark-frontend routing changes. There is no post-measurement change to statgpu/panel/**, dev/benchmarks/validate_panel_stage_c_gpu.py, or dev/benchmarks/benchmark_panel_stage_c_covariance.py; therefore the accepted P100 evidence remains applicable under RELEASING.md.

Exact-final hosted gates

All permanent workflows are successful on e16df4c966c3230edcf921cf18d23f583cb05aa1:

• Tests
• Panel Stage C external covariance
• Panel Stage C Torch CPU
• Maintenance compatibility
• Release notes validation
• Release package validation
• Benchmark Frontend CI
  • Python 3.9 / 3.11 parser + strict-source validation
  • deterministic staleness
  • frontend typecheck/build
  • Chromium E2E
  • Chromium/Firefox/WebKit production QA

Frontend/docs generated benchmark data, parse report, and source inventory are byte-identical by Git blob.

Final conclusion

Lifecycle hard exit: COMPLETE. PR #126 is ready for review/merge consideration.

Merge is intentionally not performed by this lifecycle; merge remains a separate explicit action.

[TheHiddenObserver]

Plan review/fix checkpoint on exact head ff6ccdd289d50b304c4c95e3c2501a7f5b7a6316.

Reviewed dev/plans/panel_p1_stage_c_covariance_plan.md independently against Issue #93, merged Stage A/B contracts, .claude/workflows/new-module-dev.md, .claude/skills/code-review.md, current panel covariance/estimator code, and the official linearmodels 7.0 covariance definitions.

Plan findings fixed across the review loop:

• RandomEffects covariance options are keyword-only after the existing alpha/device/n_jobs positional contract;
• Driscoll–Kraay now pins the exact full-rank linearmodels-compatible scaling and separately documents the rank-deficient statgpu pseudoinverse extension;
• physical CUDA acceptance explicitly covers every new HC integration for PooledOLS, PanelOLS, RandomEffects, BetweenOLS, and FirstDifferenceOLS on both CuPy and Torch;
• Quadratic Spectral kernel semantics are corrected: bandwidth is a smoothing scale and QS uses all observed lags, unlike Bartlett/Parzen cutoff support;
• historical HC1 (robust), Pooled row-HAC, uncorrected cluster covariance, Stage-B df behavior, and classical Hausman applicability remain frozen.

Fresh plan audit result: CRITICAL 0 / HIGH 0 / relevant MEDIUM 0. Plan is implementation-ready; implementation now proceeds under the same active gates. PR remains Draft.

[TheHiddenObserver]

Fresh .claude/skills/code-review.md checkpoint on exact head 9c0b3050dd143c43a06bb6393d69f4f83e861637 (auto-fix; changed + adjacent review).

Active axes: inference, public API, NumPy/CuPy/Torch backend behavior, formula/data alignment, external statistical definitions, physical acceptance, performance/provenance, tests, docs/artifacts.

This cycle fixed the remaining actionable findings, including: permanent estimator-level external CI coverage (Pooled/Panel/RandomEffects), public covariance primitive group_debias fail-closed validation, documented oversized Bartlett/Parzen DK extension versus linearmodels 7.0 rejection, explicit high-T QS performance coverage/schema, public primitive backend auto-detection when xp is omitted, and direct CuPy/Torch public-primitive physical acceptance design. Temporary review workflows/helpers were removed from the final tree.

Exact-head permanent hosted gates are all successful: Tests, Panel Stage C external covariance, Panel Stage C Torch CPU, Maintenance compatibility, Release notes validation, Release package validation, and Benchmark Frontend CI (including production QA).

Latest fresh review: 0 CRITICAL, 0 HIGH, 0 relevant MEDIUM; no unresolved review threads.

Hard exit: PARTIAL_REMOTE_PENDING. The only remaining acceptance gate is exact-clean-head physical P100 evidence from dev/benchmarks/validate_panel_stage_c_gpu.py plus dev/benchmarks/benchmark_panel_stage_c_covariance.py for both CuPy and Torch. Keep PR Draft until those artifacts are audited and a post-evidence fresh review is clean.

[TheHiddenObserver]

Fresh exact-final .claude/skills/code-review.md review on e16df4c966c3230edcf921cf18d23f583cb05aa1.

Active gates reviewed: correctness/inference, NumPy-CuPy-Torch backend behavior, public API, pinned external definitions, physical GPU provenance, performance protocol, benchmark canonicalization/catalog/coverage, generated artifacts, docs/changelogs, and regression/packaging CI. Loss/penalty/solver/CV gates are not active for this Stage-C scope except where shared hosted regression suites exercise them.

Findings after the final review/fix loop:

• CRITICAL: 0
• HIGH: 0
• relevant MEDIUM: 0
• unresolved review threads: 0

Physical evidence:

• Exact clean measurement SHA: 9c0b3050dd143c43a06bb6393d69f4f83e861637.
• Artifact repository commit: 85d710bddf633134624501a9e27f03c30bc04ead.
• Tesla P100 correctness: 26 estimator covariance cases + 2 direct public covariance primitives per backend, 28/28 CuPy and 28/28 Torch, requested/executed backend identity, no CPU fallback.
• Correctness canonical source: panel-stage-c-validation-pr126-20260810-a0d258f6d6b8, 56 validation-only rows, raw SHA-256 a0d258f6d6b8243e82684a29305606e5f6bd91bbe271c3ed335b32b5ec973665.
• Performance canonical source: panel-stage-c-performance-pr126-20260810-214284f02a5e, 58 synchronized timing rows, raw SHA-256 214284f02a5e21e775e58deaf2fa3cc9b6384d392b96c6f300f31f4a02953b1; includes 4 explicit N=10,000, k=2, T=200 QS all-lag rows and makes no speedup claim.

Post-evidence review fixes were completed before this review:

• performance canonicalization now uses T-specific scale identities (..._t20 vs ..._t200) so dashboard scale filtering cannot collapse the representative high-T scenario;
• the performance parser fail-closes on the exact 54-row base Cartesian matrix and exact 4-row high-T backend/case matrix;
• all manifest/source-count contracts were updated from 11 to 13 sources;
• temporary promotion/review workflows and helpers are absent from the final tree.

Physical evidence applicability audit: comparing measurement 9c0b3050... to final candidate e16df4c... shows only evidence, parser/manifest/catalog/coverage, tests, generated assets, changelogs/review record, and permanent benchmark-frontend routing changes. There is no change to statgpu/panel/**, dev/benchmarks/validate_panel_stage_c_gpu.py, or dev/benchmarks/benchmark_panel_stage_c_covariance.py after measurement, so the accepted P100 evidence remains applicable under RELEASING.md.

Generated artifact audit: frontend/docs copies are byte-identical by Git blob for benchmark data, parse report, and source inventory. Stage-C raw sources are immutable SHA-256-protected required canonical sources with explicit measurement/artifact provenance.

Exact-final hosted CI on e16df4c966c3230edcf921cf18d23f583cb05aa1: SUCCESS for Tests, Panel Stage C external covariance, Panel Stage C Torch CPU, Maintenance compatibility, Release notes validation, Release package validation, and Benchmark Frontend CI. Benchmark Frontend includes Python 3.9/3.11 parser+strict-source validation, deterministic staleness, typecheck/build, Chromium E2E, and Chromium/Firefox/WebKit production QA.

Hard exit: COMPLETE. This review considers PR #126 ready to leave Draft. This review does not merge the PR; merge remains a separate explicit action.

[cursor]

Bugbot is not enabled for your account, so this pull request was not reviewed.

Enable Bugbot in the Cursor dashboard to get automatic reviews on future PRs.

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.