(tooling): docs-sync pre-commit hook stages phantom src/content/docs/** paths when committing from a worktree

[fhuthmacher]

Component

CDK / infrastructure — repo tooling (prek / pre-commit hooks)

Describe the bug

The docs-sync pre-commit hook (.pre-commit-config.yaml) fails during a real git commit from a linked git worktree (.worktrees/<branch>/, which AGENTS.md mandates for all feature work). The commit is blocked with:

sync docs → Starlight mirrors....Failed
- hook id: docs-sync
- files were modified by this hook

and git status fills with ~68 phantom src/content/docs/** entries staged at the repo root (AD — present in the index, absent on disk), e.g.:

AD src/content/docs/architecture/Api-contract.md
AD src/content/docs/index.md
AD src/content/docs/using/Jira-setup-guide.md
... (~68 total)

The real Starlight mirror under docs/src/content/docs/ is regenerated correctly — only these root-relative phantom paths are spurious, and they block the commit.

Expected behavior

Committing an edit to a file matching the hook's files: pattern (docs/(design|guides)/*.md or CONTRIBUTING.md) from a worktree regenerates the mirror, stages only the real docs/src/content/docs/** files, and the hook passes.

Current behavior

• Reproduces only on a real git commit from a worktree — not via prek run docs-sync ... (which passes cleanly). This points at prek's commit-time behavior (it stashes unstaged changes during the run), not the sync script itself.
• The hook entry is:

  entry: bash -lc 'cd "$(git rev-parse --show-toplevel)/docs" && node scripts/sync-starlight.mjs && git add src/content/docs/'

  In a worktree, git rev-parse --show-toplevel correctly returns the worktree root, and sync-starlight.mjs resolves its output to docs/src/content/docs/ correctly. Running the entry line manually stages the right path. Yet under a real commit, ~68 root-relative src/content/docs/** paths end up AD in the index.
• Workaround: git reset, explicitly stage the intended files, and commit with --no-verify (after verifying the mirror out-of-band with mise //docs:sync).

Reproduction steps

1. git worktree add .worktrees/docs-fix -b docs/test origin/main
2. cd .worktrees/docs-fix && mise run install
3. Append a line to docs/guides/LINEAR_SETUP_GUIDE.md and git add it.
4. git commit -m "docs: test" (run through mise exec -- so the astro check hook gets Node 22 — see the related Node-version issue).
5. Observe: docs-sync reports Failed — "files were modified by this hook", and git status shows ~68 phantom AD src/content/docs/** entries at the repo root while the real mirror under docs/src/content/docs/ is correct.

Note: prek run docs-sync --files docs/guides/LINEAR_SETUP_GUIDE.md does not reproduce it — the failure is specific to the full commit path.

Possible solution

Not root-caused with confidence; the trigger is the commit-time path (prek stash + the hook's git add), not the sync script. Candidate directions to investigate:

• Make the hook's git add target explicit and worktree/cwd-independent so it cannot resolve against an unexpected root during prek's stash/restore, e.g. git -C "$(git rev-parse --show-toplevel)" add docs/src/content/docs/.
• Confirm whether prek's partial-stash step interacts badly with a hook that both writes files and stages them, in a worktree specifically.

Node version

22.23.1 (via mise)

mise version

2026.7.13

Local modifications

Discovered while committing an unrelated CLI fix from a worktree at .worktrees/. No changes to the hook itself; the symptom is independent of the committed content.

Additional context

AGENTS.md requires all feature work in a worktree under .worktrees/<branch>/, so this affects the mandated workflow for any change touching docs/guides/, docs/design/, or CONTRIBUTING.md. Related issue: astro check hook fails under bare Node v20 unless the commit runs through mise exec (filed separately).