refactor(hooks): centralize thresholds and drop dead code by AJ-EthereaLogic-ai · Pull Request #49 · Org-EthereaLogic/spec-driven-docs-system

Anthony Johnson II (AJ-EthereaLogic-ai) · 2026-06-17T22:47:19Z

Summary

Cleanup pass over the documentation hooks — no behavior change at default config.

hook_utils.py: adds MIN_DOCUMENT_WORDS (50), MAX_PARAGRAPH_WORDS (200), DEFAULT_PUBLISH_THRESHOLD (80), and get_publish_threshold() which reads grades.B.min from quality-gates.json.
doc_post_review.py: score-only publish/readiness derivation now uses the configured Grade B threshold instead of a hardcoded 80.
doc_post_write.py: uses the shared paragraph threshold; removes the dead seen_lines set (line indices are already unique within each variant pass).
doc_pre_write.py: removes the unreachable non-fenced Protocol-ellipsis handler (valid code examples belong inside fenced blocks, which _fenced_code_spans() already allows); hoists content.lower() out of the forbidden-pattern loop.

Verification

get_publish_threshold(.) → 80, matching grades.B.min (default behavior preserved).
Non-fenced ellipsis flagged; fenced ellipsis allowed.
.codex hook mirror byte-identical to .claude sources (parity).

Tests

Added smoke regression (Test 8e): post-review honors a configured Grade B threshold (sets grades.B.min=86, score 85 → no promotion).
Full suite: 38 passed / 0 failed (includes .codex parity + markdownlint).

🤖 Generated with Claude Code

Summary by CodeRabbit

Release Notes

New Features
- Documentation publish thresholds are now configurable per project via quality-gates settings.
- Paragraph readability suggestions now use configurable word-count parameters.
Improvements
- Enhanced ellipsis detection in documentation validation with improved line-number reporting.
- Optimized pattern-matching performance in validation checks.

- Add MIN_DOCUMENT_WORDS, MAX_PARAGRAPH_WORDS, DEFAULT_PUBLISH_THRESHOLD and get_publish_threshold() (reads grades.B.min) to hook_utils.py. - doc_post_review.py: derive the score-only publish threshold from quality-gates.json instead of a hardcoded 80. - doc_post_write.py: use the shared paragraph threshold and remove the dead seen_lines set (line indices are already unique per pass). - doc_pre_write.py: drop the unreachable non-fenced Protocol ellipsis handler (valid examples belong in fenced blocks) and hoist content.lower() out of the forbidden-pattern loop. - smoke.sh: add a regression asserting post-review honors the configured Grade B threshold. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

coderabbitai · 2026-06-17T22:47:30Z

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 0599cff0-9e6d-48a4-af30-76acb20a3d7d

📥 Commits

Reviewing files that changed from the base of the PR and between 0ff8784 and 076e41e.

📒 Files selected for processing (5)

.claude/hooks/doc_post_review.py
.claude/hooks/doc_post_write.py
.claude/hooks/doc_pre_write.py
.claude/hooks/hook_utils.py
tests/smoke.sh

📝 Walkthrough

Walkthrough

Hardcoded numeric thresholds (50, 200, 80) across the three doc hooks are replaced with shared constants (MIN_DOCUMENT_WORDS, MAX_PARAGRAPH_WORDS, DEFAULT_PUBLISH_THRESHOLD) exported from hook_utils. A new get_publish_threshold helper reads the Grade B minimum from quality-gates.json. The Protocol/ABC ellipsis validator is removed, and a smoke test verifies the dynamic threshold path.

Changes

Configurable thresholds and shared constants across hooks

Layer / File(s)	Summary
hook_utils constants and `get_publish_threshold` `.claude/hooks/hook_utils.py`	Adds `MIN_DOCUMENT_WORDS`, `MAX_PARAGRAPH_WORDS`, `DEFAULT_PUBLISH_THRESHOLD` constants and `get_publish_threshold(project_dir)` which reads `grades.B.min` from `quality-gates.json`, falling back to `DEFAULT_PUBLISH_THRESHOLD` on any error. Updates the `"Ellipsis"` fix-hint wording.
doc_pre_write and doc_post_write consume shared constants `.claude/hooks/doc_pre_write.py`, `.claude/hooks/doc_post_write.py`	`doc_pre_write` imports `MIN_DOCUMENT_WORDS`, computes `content_lower` once before iterating forbidden patterns, and removes `is_valid_protocol_ellipsis`—`check_ellipsis_patterns` now flags all `...` outside fenced code blocks. `doc_post_write` imports `MAX_PARAGRAPH_WORDS` to replace the hardcoded `200` check and removes the `seen_lines` deduplication in the terminology loop.
doc_post_review uses dynamic publish threshold `.claude/hooks/doc_post_review.py`	Removes hardcoded `PUBLISH_THRESHOLD = 80`; imports `get_project_dir` and `get_publish_threshold` to compute the threshold at runtime inside `extract_review_results`.
Smoke test for configurable threshold `tests/smoke.sh`	`run_post_review_hook` gains an optional `project_dir` argument. New Test 8e writes a temp `quality-gates.json`, sets a custom Grade B min, and asserts the hook emits no promotion output when the input score is below that threshold.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐇 No more magic numbers hiding in the code,
The thresholds now live where they should abode!
Ellipsis guessing? Simplified away,
A config file decides the publish day.
Hop hop hooray, the constants now align! ✨

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch refactor/centralize-hook-thresholds

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

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

Copilot

The job was not started because the account is locked due to a billing issue.

codacy-production · 2026-06-17T22:48:06Z

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics -7 complexity · 0 duplication

Metric Results

Complexity -7

Duplication 0

View in Codacy

_{NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer}
_{TIP This summary will be updated as you push new changes.}

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

chatgpt-codex-connector

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 076e41efa3

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

Open a pull request for review
Mark a draft as ready
Comment "Codex (@codex) review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "Codex (@codex) address that feedback".

chatgpt-codex-connector · 2026-06-17T22:51:21Z


    results["passed"] = extract_bool("passed")
    results["ready_for_publish"] = extract_bool("ready_for_publish")
+    publish_threshold = get_publish_threshold(get_project_dir())


Keep promotion suggestions aligned with /doc-promote

When projects customize grades.B.min away from 80, this hook now derives score-only readiness from that value, but the suggested next step still calls /doc-promote, whose rough_draft→pending_approval gate is hard-coded to score ≥80 in .claude/commands/doc/doc-promote.md lines 51 and 104. For example, B.min=75 makes a score-only 75 review emit a promotion suggestion that /doc-promote will block, while B.min=86 suppresses a score 85 suggestion even though /doc-promote would pass it; keep this hook on the same threshold as the promotion command or update both together.

Useful? React with 👍 / 👎.

Copilot AI review requested due to automatic review settings June 17, 2026 22:47

Copilot stopped reviewing on behalf of Anthony Johnson II (AJ-EthereaLogic-ai) due to an error June 17, 2026 22:47
The job was not started because the account is locked due to a billing issue.

Copilot AI reviewed Jun 17, 2026

Anthony Johnson II (AJ-EthereaLogic-ai) merged commit 0562351 into main Jun 17, 2026
2 of 10 checks passed

Anthony Johnson II (AJ-EthereaLogic-ai) deleted the refactor/centralize-hook-thresholds branch June 17, 2026 22:47

Anthony Johnson II (AJ-EthereaLogic-ai) added a commit that referenced this pull request Jun 17, 2026

docs(changelog): record hook threshold centralization (PR #49)

b7b8a02

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Anthony Johnson II (AJ-EthereaLogic-ai) mentioned this pull request Jun 17, 2026

docs(changelog): record hook threshold centralization (PR #49) #50

Merged

Anthony Johnson II (AJ-EthereaLogic-ai) added a commit that referenced this pull request Jun 17, 2026

docs(changelog): record hook threshold centralization (PR #49) (#50)

9296862

Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

chatgpt-codex-connector Bot reviewed Jun 17, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

refactor(hooks): centralize thresholds and drop dead code#49

refactor(hooks): centralize thresholds and drop dead code#49
Anthony Johnson II (AJ-EthereaLogic-ai) merged 1 commit into
mainfrom
refactor/centralize-hook-thresholds

Anthony Johnson II (AJ-EthereaLogic-ai) commented Jun 17, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jun 17, 2026 •

edited

Loading

Review failed

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

codacy-production Bot commented Jun 17, 2026

Uh oh!

chatgpt-codex-connector Bot left a comment

Uh oh!

chatgpt-codex-connector Bot Jun 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Conversation

Anthony Johnson II (AJ-EthereaLogic-ai) commented Jun 17, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Verification

Tests

Summary by CodeRabbit

Release Notes

Uh oh!

coderabbitai Bot commented Jun 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review failed

Walkthrough

Changes

Estimated code review effort

Poem

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

codacy-production Bot commented Jun 17, 2026

Up to standards ✅

Uh oh!

chatgpt-codex-connector Bot left a comment

Choose a reason for hiding this comment

💡 Codex Review

Uh oh!

chatgpt-codex-connector Bot Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Anthony Johnson II (AJ-EthereaLogic-ai) commented Jun 17, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jun 17, 2026 •

edited

Loading