agents-lint pre-commit hook (#5286) flags AGENTS.md under .claude/worktrees/ as missing frontmatter

Open Beginner friendly
#6,531 0 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
78/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
git, node.js, yaml
Domain
tooling

Research direction

Inspect .pre-commit-config.yaml and .agents-lint.json, starting with the agents-lint hook's filename matching and existing ignore patterns. Reproduce the failure with a nested .claude/worktrees//AGENTS.md, then verify that the exclusion prevents nested copies from being linted while the repository root file remains checked.

Written by the indexing model from the issue text.

Description

ci-cd priority: low

agents-lint pre-commit hook flags any markdown under .claude/worktrees/ as a memory file missing frontmatter

PR #5286 ("docs: add repository agent guidance with root-only enforcement", still open/draft) adds an agents-lint local hook to .pre-commit-config.yaml:

-   id: agents-lint
    name: agents-lint (AGENTS.md freshness)
    entry: agents-lint
    language: node
    additional_dependencies: [agents-lint@0.5.0]
    files: ^(AGENTS|CLAUDE|GEMINI)\.md$
    pass_filenames: true

The files regex matches by basename pattern with no path exclusions, and .agents-lint.json on that branch only carries ignorePatterns for two unrelated theme/migration paths. The Claude Code harness creates git worktrees under .claude/worktrees/<name>/ when a task runs in an isolated worktree, and each such worktree contains its own checked-out copy of the repo root, including AGENTS.md. Committing inside one of those worktrees runs pre-commit against files under .claude/worktrees/<name>/AGENTS.md, which matches the hook's basename pattern and gets linted as if it were the repository's canonical memory file — failing with "Memory file is missing frontmatter" (or whatever agents-lint@0.5.0 expects) even when AGENTS.md is completely unchanged and passes fine in CI (which only ever lints the real root-level file, never a worktree copy).

Fix: add a path exclude for .claude/ (either as a hook-level exclude regex in .pre-commit-config.yaml, or an ignorePatterns entry in .agents-lint.json if the tool supports path-based excludes) so nested worktree copies of these filenames are never linted.

Found while committing to #5286 on 2026-09-13.

Dominant language
Python
Stars
9.1k
Forks
824
Avg merge
3d 4h
Merged PRs (30d)
289

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from LearningCircuit/local-deep-research

All issues in LearningCircuit/local-deep-research

Similar issues

More Python issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.