build: doc-path audit — verify every prose file-ref points at a real …

[awais786]

…file

Why

The bidirectional spec-coverage audit handles drift for tests ↔ specs. What it doesn't handle is drift for prose ↔ files: a file gets renamed, a doc gets moved to docs/archive/, a helper changes location — and CLAUDE.md / README.md / skills.md / TRIAGE.md / docs/*.md keep referencing the old paths long after the link is dead.

PR #55 (docs-consolidation) made this concrete: archiving 3 historical files could have silently broken any cross-doc reference to them. The gate would not have caught it.

What

Adds scripts/check-doc-paths.sh — a pure-bash audit:

• Walks CLAUDE.md, README.md, skills.md, TRIAGE.md, TESTS.md, and every current docs/*.md (the archive dir + test-review snapshots are explicitly excluded — they're time-bound).
• Extracts two kinds of file references:
  1. Markdown-link targets: [text](./path) / [text](path)
  2. Backtick literals that look like paths (contain / AND end in a known extension or /)
• Resolves each candidate first relative to the doc, then relative to the repo root (the prose convention in docs/ is repo-root-relative).
• Ignores: URLs, glob/brace patterns, placeholder interpolation, HTTP/API endpoint paths (/api/users/me, /oauth2/sign_out, /god-mode/, ...), generated artefacts (playwright-report/, node_modules/), and a small documented allowlist for cross-repo refs (foss-server-bundle/) + not-yet-built files (.github/workflows/e2e-prod.yml — referenced in README but the production workflow hasn't shipped).
• Returns non-zero if any ref points at a missing file. Output lists each break as <file>:<line>: missing → <raw_path>.

Wired into:

• make audit-paths (callable on its own)
• make pre-commit (alongside typecheck + spec-coverage audit)
• .github/workflows/doc-path-audit.yml (runs on PRs that touch any *.md, the script, or its workflow; runs on push to main)

Fixed by this run

The audit immediately surfaced 3 real broken refs in the existing docs:

• CLAUDE.md:116 — app-rules/RULES.md → correct path is vendor/openspec/skills/app-rules/RULES.md
• README.md:292 — security/ → should be tests/security/
• TRIAGE.md:41 — security/headers.spec.ts → should be tests/security/headers.spec.ts

Each found and fixed in this commit.

Counts

Final audit run: 270 references checked across 7 files, 0 missing. Pre-commit gate green (typecheck + spec-coverage + doc-path).

Out of scope (follow-up notes)

• .github/workflows/e2e-prod.yml is referenced in README but not yet built. Added to IGNORED_PATTERNS with a TODO comment; remove the ignore once the production workflow ships.
• docs/test-review-*.md and docs/archive/* are excluded by design (time-bound snapshots). If we want them audited too, revisit the exclusion list.

Motivation / Background

This Pull Request has been created because:

• Resolves #issue-id

Detail

This Pull Request changes:

Additional information

TIP: Provide additional information such as screenshots, benchmarks, reference to other repositories or alternative solutions

Checklist

Before submitting the PR make sure the following are checked:

• This Pull Request is related to one change. Changes that are unrelated should be opened in separate PRs
• Commit message has a detailed description of what changed and why. If this PR fixes a related issue include it in the commit message. Ex: [Fix #issue-number]
• Tests are added or updated if you fix a bug or add a feature
• CHANGELOG files are updated for the behavior change or additional feature (minor bug fixes and documentation changes should not be included)
• This PR contains API changes and API documentation is updated accordingly (for critical or behavior change, please inform related parties about them).