feat(githooks): docstring scanner leg B, date-gated touched ratio

[hyperpolymath]

What

Adds leg B to the canonical docstring scanner .githooks/docstring-scan.sh (#1073):

• Leg B: documented / (documented + undocumented) over all touched (added + modified) functions, skipped files excluded, below DOCSTRING_THRESHOLD (default 80) is a violation. This is the ratio CodeRabbit's Docstring Coverage check reports.
• Phase-in: a self-flipping date gate with the same shape as scripts/check-docs-presence.sh (valid_date/require_date, plus a DOCS_TODAY seam). ENFORCE_DOCSTRINGS_FROM defaults to 2026-11-01 (owner ruling 2026-10-01). Before the cutoff, a leg-B violation under --check prints a WARN leg B line on stderr and leaves the exit code unchanged. From the cutoff date onward, --check exits 1.
• Leg A is unchanged: an added undocumented function still makes --check exit 1.
• Zero touched functions gives legb=n/a, and under --check the scanner says so on stderr. A vacuous ratio counts as neither a pass nor a fail.
• Fail loud: a malformed ENFORCE_DOCSTRINGS_FROM or DOCS_TODAY, or a DOCSTRING_THRESHOLD that is not an integer 0-100, exits 2 in every mode. A bad value cannot silently disarm the gate.
• Integer verdict: the check is d*100 < T*n, so exactly 80% passes and 79.17% fails.
• SUMMARY gains threshold=T legb=pass|fail|n/a, appended at the end only. The one consumer I found is the ~/.claude docstring Stop hook. It drops the SUMMARY line, reads only added/undocumented TSV rows, and runs without --check, so this PR changes nothing for it. Nothing in this repo parses SUMMARY apart from the test suite.

Tests (scripts/tests/docstring-scan-test.sh): 72 passed, 0 failed locally. The full run-shell-test-suite.sh passed all 63 files.

• The existing leg-A assertions now run with leg B disarmed (DOCSTRING_THRESHOLD=0). Without that, "editing an undocumented legacy body does not block" would flip red on 2026-11-01.
• New fixtures cover:
  • before the cutoff: WARN and rc 0
  • on the cutoff date and after it: rc 1
  • ENFORCE_DOCSTRINGS_FROM override
  • no --check: rc 0
  • exactly 80% passes; 79.17% fails
  • zero touched: no verdict, rc 0
  • skipped files in both directions: 3/4 fails beside a skipped file, which would read 4/5 if skipped counted as documented; 4/5 passes beside a skipped file, which would read 4/6 if skipped counted as undocumented
  • malformed dates and thresholds: rc 2
• Known-answer calibration controls. Each one fetches commits by full SHA into a throwaway repo, and an unfetchable commit counts as a FAILURE ("a skip is not a pass"). Both match CodeRabbit's verdict at the head it reviewed:
  • hyperpolymath/panll 964f9563..61141fb3 gives 2 documented of 22, legb=fail.
  • hyperpolymath/nextgen-databases fc12a2eb..e12e4c71 gives 2 documented of 22, legb=fail.
  • Leg A also fires on both ranges (9 added undocumented each), so these controls assert SUMMARY fields, not exit codes.

Mutants (run through the SCANNER= seam; each passed bash -n and differed from the original under cmp)

Mutant	Reds
ratio -lt → -le	4: the two exactly-80% fixtures (each asserts verdict and rc)
date compare < → >	6: before-cutoff rc0 and WARN, after-cutoff, ENFORCE override, 79.17% rc, skipped rc
skipped counted as undocumented in the denominator	2: 4/5 passes beside a skipped file (verdict and rc)
skipped counted as documented	2: 3/4 fails beside a skipped file (verdict and rc)

A planted bad calibration SHA reds the control as commits present … absent. shellcheck is clean, and both files stay 0755.

🤖 Generated with Claude Code

https://claude.ai/code/session_01Hw7qg3u9PAP6b2oKyVTSVC

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 56 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Advanced

Run ID: eeea74f3-78e8-4f0f-a0f3-d65bf0af5fb8

📥 Commits

Reviewing files that changed from the base of the PR and between 658ded3 and a0365f5.

📒 Files selected for processing (2)

• .githooks/docstring-scan.sh
• scripts/tests/docstring-scan-test.sh

• Autopilot · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Autopilot is currently an internal CodeRabbit preview.

---

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.}

[coderabbitai]

Autopilot could not be updated. Open Coding to check access and billing.