fix(hooks): fail open when the inventory script is absent from the worktree

[BigSimmo]

Closes ledger row #151 (originally #143).

Summary

core.hooksPath is an absolute path to the primary checkout, so .githooks/pre-commit runs from every linked worktree — including ones whose branch predates the docs-sync tooling and therefore does not contain scripts/update-docs-inventory.mjs. Those commits aborted before the author could do anything about it:

[pre-commit] Synchronizing generated documentation...
Error: Cannot find module '<worktree>/scripts/update-docs-inventory.mjs'

This repository currently has ~45 worktrees, many on branches older than that script, so the failure is not hypothetical — it blocked a commit during the 2026-07-30 organisation session and had to be worked around per-command.

The inventory task now drops itself when its script is missing, removes docs/scripts-index.md from docs_to_check, and re-checks the all-tasks-empty early exit. Two details that are easy to get wrong:

• The re-check is load-bearing. Without it, dropping the only selected task leaves docs_to_check empty, and the trailing git diff --name-only -- then matches every modified file in the tree — failing the commit for entirely unrelated reasons.
• The grep -v needs || true. It exits 1 when it filters everything out, and set -eu is active, so without it the guard itself would abort the hook.

Verification

Tested in an isolated repository where the script genuinely does not exist. That distinction matters: simply deleting the file from a real worktree does not exercise this path, because the existing mixed-inputs guard sees the unstaged deletion and fails first — my initial attempt hit exactly that and proved nothing.

[pre-commit] scripts/update-docs-inventory.mjs is absent from this worktree - skipping inventory sync.
[main fad053e] probe
1 file changed, 1 insertion(+)

Commit succeeds, where the same input previously aborted with MODULE_NOT_FOUND.

With the script present the new block is a no-op — [ ! -f … ] is false and the re-check leaves all three task flags untouched — so the normal path is unchanged. sh -n passes. Prettier does not parse shell scripts, so format:check skips this file as it always has.

Note on the superseded branch

#151 described this fix as living on codex/docs-sync-automation-pr, a never-pushed local branch. That branch is now obsolete: its script and hook reached main through other PRs, and it sits 17 commits behind with a real conflict in docs/scripts-index.md, whose count sentence main's docs:update generator now owns. This PR applies the guard to main's committed version instead, so that branch can be abandoned rather than salvaged.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Bug Fixes

  • Improved documentation inventory synchronization during commits.
  • Prevents synchronization from being silently skipped when the required generator was removed or renamed.
  • Safely skips unavailable inventory updates when appropriate and avoids unnecessary documentation changes when no tasks remain.

• Documentation

  • Added a review record documenting the pre-commit safety improvements.

[coderabbitai]

📝 Walkthrough

Walkthrough

The pre-commit hook now checks whether the inventory generator exists in HEAD before skipping synchronization, removes obsolete inventory checks when appropriate, and exits safely when no documentation tasks remain. Tests and the review ledger record this behavior.

Changes

Inventory sync safety

Layer / File(s)	Summary
Pre-commit inventory guard .githooks/pre-commit	Checks the generator in HEAD, conditionally disables inventory synchronization, removes its documentation output from checks, and exits when no tasks remain.
Regression assertion and review record tests/docs-inventory.test.ts, docs/branch-review-ledger.md	Tests the HEAD existence check and records PR-1494 in the review ledger.

Estimated code review effort: 3 (Moderate) | ~15–30 minutes

Possibly related PRs

• BigSimmo/Database#870: Updates related review ledger entries.
• BigSimmo/Database#1193: Updates rows in the same review ledger table.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the hook change to fail open when the inventory script is missing from a worktree.
Description check	✅ Passed	The description covers summary and verification well; only non-critical template sections like risk/rollback are omitted.
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 docstrings

• Create stacked PR
• Commit on current branch

---

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

[supabase]

This pull request has been ignored for the connected project sjrfecxgysukkwxsowpy because there are no changes detected in supabase directory. You can change this behaviour in Project Integrations Settings ↗︎.

---

Preview Branches by Supabase.
Learn more about Supabase Branching ↗︎.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit:62ed282dda

ℹ️ 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 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 address that feedback".

[coderabbitai]

🧹 Nitpick comments (1)

tests/docs-inventory.test.ts (1)

54-55: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Test both hook branches instead of only matching source text.

These assertions can pass while the guard is unreachable or shell-invalid. Add an isolated temporary-repository test covering both a staged generator removal (must fail closed) and a genuinely absent generator in a legacy worktree (must succeed and omit docs/scripts-index.md).

🤖 Prompt for 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.
In `@tests/docs-inventory.test.ts` around lines 54 - 55, Replace the
source-text-only assertions in the docs inventory hook test with an isolated
temporary-repository integration test that executes the hook. Cover both
branches: a staged removal of the generator must fail closed, while a genuinely
absent generator in a legacy worktree must succeed and omit
docs/scripts-index.md.

🤖 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.
Nitpick comments:
In `@tests/docs-inventory.test.ts`:
- Around line 54-55: Replace the source-text-only assertions in the docs
inventory hook test with an isolated temporary-repository integration test that
executes the hook. Cover both branches: a staged removal of the generator must
fail closed, while a genuinely absent generator in a legacy worktree must
succeed and omit docs/scripts-index.md.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 1a8cde61-75e2-4f0c-bbe1-50e2344368e4

📥 Commits

Reviewing files that changed from the base of the PR and between 3f7073f and 7b96a09.

📒 Files selected for processing (3)

• .githooks/pre-commit
• docs/branch-review-ledger.md
• tests/docs-inventory.test.ts