feat(lint): fence unit conventions with prek hooks

[olantwin]

Stacked on #73. Four pygrep fences (hardcoded c, G4SystemOfUnits.hh, CLHEP outside the bridge, magic power-of-ten factors — self-tested against pre-migration main), a docs/units.md conventions page, and unit annotations for every dimensional default in lib.libsonnet.

Summary by CodeRabbit

• Documentation

  • Added a new units guide covering quantity vocabulary, storage vs. typed views, conversion boundaries, interoperability rules, and configuration conventions.
  • Documented the expected unit/provenance annotations for workflow configuration values.

• Chores

  • Added automated pre-commit checks that prevent unsafe unit handling, disallowed unit-related includes/usages, hardcoded physical constants, and ambiguous hand-typed conversion factors.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 0d36fce6-f0fa-48f7-90ba-12ef900b4a04

📥 Commits

Reviewing files that changed from the base of the PR and between 64da977 and f7e480e.

📒 Files selected for processing (2)

• .pre-commit-config.yaml
• docs/units.md

🚧 Files skipped from review as they are similar to previous changes (2)

• .pre-commit-config.yaml
• docs/units.md

---

📝 Walkthrough

Walkthrough

The pull request documents repository unit-handling conventions, adds pre-commit checks for unsafe unit patterns, and annotates workflow configuration values with units and provenance.

Changes

Unit safety conventions

Layer / File(s)	Summary
Unit handling policy docs/units.md	Documents canonical quantity types, storage units, boundary conversion rules, interoperability guidance, and enforcement expectations.
Pre-commit unit-safety fences .pre-commit-config.yaml	Adds local pygrep hooks banning hardcoded speed-of-light constants, restricted Geant4/CLHEP includes and symbols, and hand-typed scientific conversion factors.
Workflow unit annotations workflows/lib.libsonnet	Adds inline unit and provenance comments to source-module and Geant4 crossing configuration values without changing keys or numeric values.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

• ShipSoft/aegir#64: Updates shared workflow configuration helpers touched by the annotated configuration blocks.
• ShipSoft/aegir#71: Implements the CLHEP bridge policy enforced by the new unit-safety hooks.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Description check	⚠️ Warning	The description summarizes the changes, but it omits the required checklist items for commits, pre-commit checks, and CI.	Add the checklist entries and explicitly state whether the commit message, lint, and CI requirements pass.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and accurately summarizes the main change: unit-convention lint fences.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/units-lints

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[olantwin]

@coderabbitai review

[github-actions]

Physics Metrics Comparison

1 configuration(s) have differences

• Configurations compared: 1
• With differences: 1

Configurations with Differences

comparison_physics-smoke

• Files compared: 1
• Histograms compared: 8
• Fits compared: 0
• Total differences: 4

Show differences

gun_st_nofield_smoke_validation.root:
  h_hit_edep.integral: 911 → 963 (Δ=5.708%)
  h_hit_z.integral: 911 → 963 (Δ=5.708%)
  h_hit_detector.integral: 911 → 963 (Δ=5.708%)
  h_hit_momentum.integral: 911 → 963 (Δ=5.708%)

---

About this comparison

Physics metrics are extracted from ROOT files and compared.
Default comparison uses 5% tolerance for histogram statistics
and 3σ for fit parameters.

Metrics stored in git notes: refs/notes/ci/physics-metrics/<config>

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.pre-commit-config.yaml:
- Around line 31-37: Align the unit-policy checks across all affected sites: in
.pre-commit-config.yaml lines 31-37, remove the blanket src/units/ exclusion and
match G4SystemOfUnits.hh include directives so the ban is repo-wide; in lines
39-44, narrow the CLHEP exception to src/units/clhep_bridge.hpp and detect
forbidden symbol usage rather than only header paths; update docs/units.md lines
39-42 to describe these exact exceptions.
- Around line 23-29: Expand the forbid-hardcoded-c pre-commit hook’s entry
pattern to detect equivalent speed-of-light literals, including scientific
notation such as 2.99792458e8 and 2.99792458E+8 and digit-separated 299'792'458,
while preserving boundary protection against longer unrelated numbers. Add
regression fixtures covering each supported form.
- Around line 46-53: The forbid-magic-unit-factors hook currently misses
plus-exponent notation and block-comment conversion markers. Update its entry
regex to match signed positive exponents such as 1e+3 and conversion indicators
within block comments, while preserving the existing unit-factor and
conversion-context constraints.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 4542aa36-6ff0-468e-a748-0422f5c59ed1

📥 Commits

Reviewing files that changed from the base of the PR and between 9db189c and 64da977.

📒 Files selected for processing (3)

• .pre-commit-config.yaml
• docs/units.md
• workflows/lib.libsonnet

[olantwin]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.

[olantwin]

@coderabbitai review

[coderabbitai]

✅ Action performed

Review finished.

Note: CodeRabbit is an incremental review system and does not re-review already reviewed commits. This command is applicable only when automatic reviews are paused.