Experiments/fix playwright issues

[plx]

Contains some further work on the QA scripts started in parent branch, as well as fixes for issues discovered while evaluating new QA script (and related improvements like the markdown linter).

[claude]

Pull Request Review: Validation Improvements & Markdown Linting

Summary

This PR introduces markdown linting infrastructure, improves validation workflows, refactors documentation structure, and adds an About page. The changes are well-executed and align with the repository's quality goals.

✅ Strengths

1. Excellent Markdown Linting Configuration

• Comprehensive .markdownlint.yaml with sensible defaults
• Well-documented rule choices with inline comments
• Appropriate exceptions for MDX usage (MD033, MD041)
• Good balance between strictness and prose flexibility

2. Documentation Refactoring

• Smart move: CLAUDE.md → @AGENTS.md reference (line src/components/Link.astro:1)
• Creates single source of truth in AGENTS.md
• Maintains backward compatibility for tooling

3. CI/CD Improvements

• Added Playwright browser installation step (.github/workflows/build.yml:46-47)
• Integrated markdown linting into validation pipeline (.github/workflows/build.yml:52-53)
• Properly sequenced validation steps

4. Accessibility Enhancement

• Added rel="noopener noreferrer" to external links (src/components/Link.astro:16)
• Security benefit: Prevents reverse tabnapping attacks
• Performance benefit: Isolates external page contexts

5. New About Page

• Clean structure with semantic HTML
• Proper heading hierarchy (h1 → h2)
• Good use of existing components and styles
• Maintains design consistency

🔍 Observations & Minor Suggestions

1. Package Dependencies

• Added markdownlint-cli2 (271 additions in package-lock.json)
• Dependency tree looks clean, no concerning transitive dependencies
• Consider documenting the markdown linting workflow in AGENTS.md

2. Header Navigation
The new "about" link addition is clean, but the inline / separator uses a <span> (src/components/Header.astro:31-33):

<span>
  {`/`}
</span>

This works but could be simplified to just <span>/</span> for consistency with the existing pattern.

3. Markdown Fixes Applied

• Fixed various markdown linting issues across content files
• Particularly good cleanup in Swift warts brief (src/content/briefs/swift-warts/first-trailing-closure-cannot-have-a-label.md)
• Removed trailing blank lines (src/content/briefs/testing/decision-execution-pattern.md)

4. Playwright Integration
The addition of Playwright browser installation suggests improved QA capabilities mentioned in the PR description. The dependency is already listed, so this completes the setup.

🎯 Best Practices Alignment

✅ Code Quality: Consistent formatting, clear intent
✅ Security: Added security headers for external links
✅ Performance: No performance regressions introduced
✅ Accessibility: Maintained ARIA labels, semantic HTML
✅ Testing: Enhanced CI validation pipeline
✅ Documentation: Improved structure and clarity

📋 Test Coverage

The PR includes:

• Linting checks (ESLint + markdownlint)
• Spell checking (source and built HTML)
• Build validation
• Link validation
• Playwright test setup (tests/navigation.spec.ts updated)

No test coverage gaps identified for the changes made.

🔒 Security Review

No security concerns. The PR actually improves security by:

1. Adding rel="noopener noreferrer" to external links
2. Maintaining existing security practices
3. No introduction of unsafe dependencies

🚀 Deployment Considerations

• Changes are safe for automatic deployment to GitHub Pages
• No breaking changes to existing content
• New About page adds value without affecting existing routes
• CI pipeline enhancements should catch issues before merge

💡 Recommendations

1. Documentation: Consider adding a note in AGENTS.md about the markdown linting workflow
2. Minor cleanup: Simplify the Header.astro separator span (optional, cosmetic)
3. Future enhancement: The .markdownlint.yaml is excellent - consider documenting custom rules for content authors

Final Verdict: ✅ LGTM

This PR demonstrates excellent engineering practices:

• Incremental improvement without over-engineering
• Clear commit messages
• Proper integration of new tooling
• Attention to quality and security details

Recommendation: Approve and merge. The changes are production-ready and improve the project's quality infrastructure.

---

Review conducted by Claude Code following repository conventions from AGENTS.md