chore(pre-push): make hook + CLAUDE.md instructions worktree-compatible

[k-yoshimi]

Summary

• Route the pre-push review-marker check and the SKIP-override audit log through $(cd "$(git rev-parse --git-common-dir)" && pwd) so both the main checkout and any linked worktree share the same marker set, keyed on content (SHA) rather than workspace.
• Update CLAUDE.md §Pre-push gate's documented touch command to match — the old touch .git/REVIEW_OK_$(git rev-parse HEAD) only worked from the main checkout's working tree root.

Why

A linked worktree's .git is a file (a gitdir pointer to <main>/.git/worktrees/<name>/), not a directory. Bash path traversal through a file fails, so the previous hook's literal .git/REVIEW_OK_<sha> path check always reported "no marker" when invoked from a worktree, even when a valid marker existed. The only way to push was via the SKIP_PREPUSH_REVIEW=1 escape hatch, which defeats the gate's purpose. With the fix, worktree-based PR workflows (branching off develop into ~/.config/superpowers/worktrees/<project>/<branch>/ and pushing from there) pass the gate the same way main-checkout pushes do.

The cd … && pwd round-trip also normalises the main-checkout case: git rev-parse --git-common-dir returns the literal .git (relative to CWD) there, so the error message used to print a non-copy-pasteable touch .git/REVIEW_OK_<sha> if the user wasn't shelling from the repo root. Now the error always shows an absolute path.

Test plan

Exercised in both environments:

• Main checkout (/Users/k-yoshimi/Dropbox/cursor/task): no marker → exit 1; marker present → exit 0; SKIP_PREPUSH_REVIEW=1 SKIP_PREPUSH_REVIEW_REASON=test → exit 0 and line appended to REVIEW_OVERRIDES.log.
• Linked worktree (~/.config/superpowers/worktrees/task/docs-sphinx-static-placeholder, where .git is a file): same three cases, all correct. Error message shows the absolute <main>/.git/REVIEW_OK_<sha> path.
• Actual git push from the feature branch passed the hook (see "pre-push: review marker present — OK" in the push output that created this branch).

No Fortran or Python code changed; no pytest run.

Reviewed by superpowers:code-reviewer: 0 HIGH, 1 MED addressed in this branch (the cd+pwd absolute-path fix), 1 MED + 2 LOW non-blocking.

🤖 Generated with Claude Code

---

Note

Medium Risk
Medium risk because it changes CI workflow/build ordering and introduces new Makefile/stub linkage paths for tot C-ABI tests, which can break builds across environments; the rest is largely documentation and tooling updates.

Overview
CI now exercises tot end-to-end C-ABI and equivalence coverage. The python-tests workflow is updated to run make -C tot libs + tot_api_check_all (Layer 2/4 C drivers) and to generate Layer 1 eqdata baselines for both demo2014 and ht6m, while also expanding the workflow branch filters so the long-lived chore/pre-push-hook-worktree-compat branch actually triggers Actions.

Docs and tooling are reorganized and hardened. The Sphinx manual is migrated from the old docs/sphinx/{en,ja} trees to a hybrid portal/{en,ja} + modules/<mod>/{en,ja} structure with an expanded Makefile (HTML/PDF/linkcheck targets), shared Furo theme + MyST math support, and updated README; large amounts of legacy single-tree content are removed and replaced by per-module pages (notably eq), plus a new sphinx-module-manual skill.

Developer workflow improvements. The pre-push gate is made worktree-compatible (marker stored under git --git-common-dir) and CLAUDE.md now requires an additional Codex review step; .gitignore is extended for new tot C-ABI artifacts and external dependency clones, and the LaTeX manual gets a small parameter table correction.

^{Reviewed by Cursor Bugbot for commit f0811de. Bugbot is set up for automated code reviews on this repo. Configure here.}

---

Addendum: PNBTOT Registry Extension (commits 5c12dcb..f0811de)

This branch has accumulated additional work beyond the original
pre-push-hook scope:

• 24b1b12f test+tr: backfill AJRFT in regression dump (PR tr+totlib: physical EXTERNAL_DRIVEN_I scalar (L-7b-i) #187 follow-up)
• d17f71ec test: backfill AJRFT in extractor unit-test fixture
• 5c12dcb2 feat(tr): register PNBTOT in tr_param_registry — C1
• d5b4da37 test(tr): drive ITER01 fixture with PNBTOT=25 MW (NBI on) — C2 (atomic fixture+.in+baseline)
• b28a7f87 docs(tr): wire PNBTOT through user-facing surfaces — C3 (en/ja tutorials, MCP, LaTeX)
• f0811de2 docs(tr): restore paragraph break + fix list count after PNBTOT bullet removal

Spec: docs/superpowers/specs/2026-05-05-tr-pnbtot-registry-design.md
Plan: docs/superpowers/plans/2026-05-06-tr-pnbtot-registry.md

Deferred review notes (not folded back into commit messages per CLAUDE.md no-amend rule)

C2 baseline-diff scope clarification: the commit body claims "Profile RT/AJ shifted across all 50 radial points × 11 timesteps". Empirically:

• Only RT shifted (max Δ ≈ 4.6 keV near-axis at NR=1, scaling to ~0.006 keV at NR=50 — physically plausible for centered-Gaussian 25 MW NBI on a 100-step run).
• AJ, RN, QP are bit-identical.
• tr_regress.dat captures one end-of-run snapshot, not 11 timesteps.

Why AJ unchanged despite 2× temperature rise on-axis: current is prescribed by the RIPS=2 → RIPE=7 ramp; conductivity-T (j(T)) coupling is not in the active model under MDLNF=1 + MDLNB=1 + this 100-step horizon.

C2 baseline regen environment (for future bisect reproducibility):

• Host: clavius (Linux x86_64, Ubuntu 24.04)
• Compiler: GNU Fortran 13.3.0 (Ubuntu 13.3.0-6ubuntu2~24.04)
• BPSD HEAD: dcccf84f with both upstream patches applied (docs/external-patches/bpsd/{bpsd-plasmaf-intent-out-init,bpsd-species-kid-oob-fix}.patch)
• Reproducer:

  make -C tr clean && make -C tr tr2
  ./test_run/run_tests.sh tr_iter01
  python3 test_run/scripts/extract_tr_metrics.py \
      test_run/test_output/tr_iter01/tr_regress.dat \
      > test_run/baselines/tr_iter01/metrics.json
  

Out-of-scope follow-ups (separate PRs)

• tr_tst2 baseline AJRFT backfill — depends on resolving the pre-existing eq_tst2 ~3e-9 physics drift first
• Sibling totregress + extract_tot_metrics.py AJRFT coverage gap (analogous to the trregress backfill in 24b1b12f) — silent invisibility for the totlib L-7b-i pipeline
• Property-based PNBTOT × WPT monotonicity sweep — Layer-4 work
• CI workflow staging of eqdata.ITER01 so test_equivalence.py::test_iter01 actually runs on CI (currently SKIPs, hiding the AJRFT-class drift discovered in this PR — per feedback_equivalence_must_pass.md invisibility pattern)

[k-yoshimi]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 210c90b. Configure here.}

[k-yoshimi]

@cursor review

Triggering after the AJRFT bookkeeping (24b1b12f, d17f71ec) + PNBTOT registry extension (5c12dcb2 C1, d5b4da37 C2 atomic, b28a7f87 C3 docs, f0811de2 polish) commits. CI green on push run 25644244794 + PR run 25644245749. Spec at docs/superpowers/specs/2026-05-05-tr-pnbtot-registry-design.md, plan at docs/superpowers/plans/2026-05-06-tr-pnbtot-registry.md.

Local in-house + Codex pre-push reviews returned approve with C2 commit-message accuracy fixed in PR description addendum (only RT shifted; AJ/RN/QP bit-identical; single end-of-run snapshot — verified via git diff 5c12dcb2..d5b4da37 metrics.json | grep AJ\\|QP\\|RN returning 0 lines). Out-of-scope follow-ups filed as #190/#191/#192.

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit f0811de. Configure here.}