fix(scripts): exclude generated AIDD cache from Markdown link checks

Open Beginner friendly
  • Is something wrong?
#1,112 1 comment 0 reactions 0 assignees View on GitHub

Maintainers usually reply within 1 day

Nobody has claimed this yet.

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
76/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
javascript, markdown, node.js
Domain
developer-experience, tooling

Research direction

Start in scripts/check-markdown-links.js and find where the default scan roots and ignore patterns are defined; the --ignore .aidd flag in the report shows an exclusion mechanism already exists. Reproduce with the two-step snippet (create .aidd/cache/markdown-link-repro.md, then run the script with and without --ignore .aidd) to confirm the default path is the only difference. Then check which Git hooks or validation commands invoke the script so they share the same default exclusion, and add a regression test covering both the excluded cache file and a genuine broken link in tracked Markdown.

Written by the indexing model from the issue text.

Description

Description

The repository-wide Markdown link validator scans generated artifacts under .aidd/cache/. Those files are ignored by Git and are not source Markdown, but broken links inside them still make validation fail.

The issue was reproduced on upstream/next at 829a5db6. It is independent of PR #992.

Steps to reproduce

  1. Create a generated Markdown artifact:
mkdir -p .aidd/cache
printf '# Generated cache artifact\n\n[Broken cache link](./missing-target.md)\n' \
  > .aidd/cache/markdown-link-repro.md
  1. Run the repository-wide validator:
node scripts/check-markdown-links.js
  1. Compare with an explicit cache exclusion:
node scripts/check-markdown-links.js --ignore .aidd

Actual behavior

The default Markdown link validation reports broken links from generated .aidd/cache/ content, even though the directory is excluded from Git.

In the affected development environment, 464 broken links in generated cache files caused the Markdown validation and associated Git hooks to fail.

These failures are unrelated to changes in the tracked source files.

Expected behavior

The repository-wide Markdown link validator should exclude generated AIDD cache artifacts by default.

Broken links in tracked source Markdown should continue to be detected and reported normally.

Proposed fix

  • Exclude generated .aidd/cache/ artifacts from the default Markdown link scan.
  • Preserve validation of tracked Markdown documentation, skills, actions, and references.
  • Ensure the relevant Git hooks and validation commands use the same exclusion policy.
  • Add regression coverage demonstrating that broken links in generated cache artifacts do not fail repository validation, while genuine broken links in source Markdown still fail.

Additional context

The problem was identified while validating PR #992 but is reproducible independently on next.

Temporarily moving .aidd/cache/ outside the repository allows validation to complete without changing the tracked source files. This is a workaround, not a permanent solution.

The issue should be addressed separately from Kilo-native generation.

Related: #992.

Dominant language
TypeScript
Stars
481
Forks
45
Avg merge
23h 18m
Merged PRs (30d)
106

Getting set up

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 ai-driven-dev/framework

All issues in ai-driven-dev/framework

Similar issues

More TypeScript issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.