Repository navigation
Description
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 commitfrom a worktree — not viaprek 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:
In a worktree,
entry: bash -lc 'cd "$(git rev-parse --show-toplevel)/docs" && node scripts/sync-starlight.mjs && git add src/content/docs/'
git rev-parse --show-toplevelcorrectly returns the worktree root, andsync-starlight.mjsresolves its output todocs/src/content/docs/correctly. Running the entry line manually stages the right path. Yet under a real commit, ~68 root-relativesrc/content/docs/**paths end upADin the index. - Workaround:
git reset, explicitly stage the intended files, and commit with--no-verify(after verifying the mirror out-of-band withmise //docs:sync).
Reproduction steps
git worktree add .worktrees/docs-fix -b docs/test origin/maincd .worktrees/docs-fix && mise run install- Append a line to
docs/guides/LINEAR_SETUP_GUIDE.mdandgit addit. git commit -m "docs: test"(run throughmise exec --so theastro checkhook gets Node 22 — see the related Node-version issue).- Observe:
docs-syncreports Failed — "files were modified by this hook", andgit statusshows ~68 phantomAD src/content/docs/**entries at the repo root while the real mirror underdocs/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 addtarget 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).
Activity
chore(tooling): enforce the existing quality gates and add missing on…
krokoko commentedon Nov 20, 2026
Triage: this looks resolved on
main.Fixed by #1052 (merged 2026-11-19 as bf52b90; commit 542424b of that pull request): the
docs-synchook now runsmise //docs:syncfrom the top of the working tree and stagesdocs/src/content/docs/(.pre-commit-config.yaml:76), where it used to change intodocs/and stagesrc/content/docs/. The cause was not prek's stash: git exportsGIT_DIRto hooks in a linked worktree, and with it set a git command run fromdocs/takesdocs/as the top of the work tree, so the oldgit addrecorded the mirror files under root-relative paths. Checked on main (3dbfada) in a scratch clone with a linked worktree, by running prek's commit-time entry point with the variables git gives a pre-commit hook: the old command gives "files were modified by this hook" and 79AD src/content/docs/**entries, the command on main passes and stages only the edited guide and its mirror page, also in a worktree under.worktrees/and with unstaged changes in the tree. No test pins this yet (cdk/test/scripts/git-hooks.test.tschecks other properties of the hook commands), and no issue tracks adding one.Posted from an automated sweep of the open issues. Each pull request, commit and file named above was checked against
mainat3dbfada1. The issue is left open for a maintainer to close.