Skip to content

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

Open

Description

@waewoo

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Fields

    Priority

    None yet

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions