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

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.

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

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

2. Run the repository-wide validator:

   node scripts/check-markdown-links.js

3. Compare with an explicit cache exclusion:

   node scripts/check-markdown-links.js --ignore .aidd

Actual behaviour

The global scan reports the broken link under .aidd/cache/ and exits with status 1.

The same behaviour occurs in the Markdown-links pre-commit command, which runs a repository-wide scan without excluding .aidd/cache/.

When scripts/__tests__/check-markdown-links.test.js is selected by pnpm test:changed, its repository-scan tests also fail because they invoke the validator without paths.

Expected behaviour

Repository-wide Markdown validation ignores generated artifacts under .aidd/cache/ while continuing to scan real Markdown files elsewhere in the repository.

The entire .aidd/ directory must not be excluded. Markdown files outside .aidd/cache/ must remain covered.

Explicitly requested paths must preserve the validator's existing contract. Passing a file under .aidd/cache/ explicitly should still check that file unless the caller explicitly asks for an ignore.

Root cause

scripts/check-markdown-links.js starts its default traversal at the repository root. Its permanent directory exclusions do not include .aidd/cache/, and the traversal is filesystem-based rather than Git-aware, so .gitignore has no effect.

The existing --ignore option is only a caller-provided exclusion. The pre-commit hook excludes cli/tests/fixtures and cli/aidd_docs/tasks, but not .aidd/cache/.

Affected files

• scripts/check-markdown-links.js
• scripts/__tests__/check-markdown-links.test.js
• lefthook.yml

Proposed solution

Add a targeted, permanent exclusion for .aidd/cache/ during repository-wide traversal.

Preserve:

• broken-link detection for repository source files;
• explicit-path behaviour;
• existing exclusions;
• exported functions and their current contracts;
• the checks used by local hooks and CI.

Add a regression test using a synthetic Markdown file with a broken link under .aidd/cache/.

Acceptance criteria

• A repository-wide scan ignores Markdown files under .aidd/cache/.
• Markdown files elsewhere under .aidd/ remain scanned.
• An explicitly requested file under .aidd/cache/ is still checked unless explicitly ignored.
• The regression test proves that a broken link in .aidd/cache/ does not fail the global scan.
• Existing broken-link detection and exported function behaviour remain unchanged.
• pnpm test:changed and the Markdown pre-commit check pass with generated cache artifacts present.
• The existing test suite and CI validation pass.

AI tool / OS / version

• AI tool: Codex
• OS: Linux
• aidd-cli version: Not required for reproduction

Additional context

PR #992 exposed the problem while validating Kilo-native generation, but does not own this defect and is not a dependency for fixing it.