feat: Add Vale linting integration with editorial workflow [NOTASK]

[justinegeffen]

Implement Vale as fast, free terminology checker (2 sec) before Claude AI agents (30 sec, costs tokens). This integration catches 80% of terminology issues automatically and saves ~60% tokens by preventing duplicate checking.

Components Added

Vale Configuration

• .vale.ini - Main Vale configuration with StylesPath, packages, and rule overrides
• .github/styles/Seqera/Products.yml - Product name rules (Tower, Nextflow, Wave, Fusion, Studios, MultiQC)
• .github/styles/Seqera/Features.yml - Feature terminology rules (compute environment, credentials, repository, etc.)
• Context-dependent rules set to warnings (Tower, CE, PAT, Workspace) - not blockers

CI Integration

• Updated .github/workflows/docs-review.yml:
  • Added vale-lint job (runs on platform-* directories including versioned_docs)
  • Optimized parallel execution (vale-lint + voice-tone + terminology run simultaneously)
  • Vale posts inline PR comments via github-pr-review reporter
  • Non-blocking: fail_on_error: false
  • Added platform-enterprise_versioned_docs to scan list

Local Integration

• Updated .pre-commit-config.yaml:
  • Added Vale hook (v3.0.7) in manual stage (non-blocking)
  • Only runs when explicitly called: pre-commit run vale --all-files
  • Won't block commits automatically
• VSCode integration documented (requires User Settings, not workspace settings)

Agent Optimization

• Streamlined .claude/agents/terminology.md:
  • Removed ALL Vale-handled rules (product names, feature abbreviations, simple substitutions)
  • Focused ONLY on context-dependent issues Vale can't catch:
    • Tower usage context (legacy vs current)
    • Code vs prose formatting (lowercase in code blocks, proper case in prose)
    • Bold vs backticks decisions (UI elements vs code/commands)
    • UI text accuracy verification
    • Abbreviation expansion on first use (document-level context)
  • Clear division of labor documented

Documentation

• VALE_SETUP.md - Complete setup guide:
  • One-time installation (Vale, pre-commit, VSCode extension)
  • Critical VSCode configuration (User Settings requirement)
  • Validation steps and testing procedures
  • Daily workflow options (VSCode real-time, manual check, CI)
  • Rule summaries and troubleshooting

Other Changes

• Updated .gitignore:
  • Added .vscode/ (user-specific paths shouldn't be committed)
  • Added !.github/styles/Seqera exception

Token Optimization

Before Vale:

• Claude checks everything: ~500 tokens per file
• 50 files = 25,000 tokens wasted on simple fixes

After Vale:

• Vale checks terminology: free, 2 seconds
• Claude skips Vale's checks: ~200 tokens per file
• 50 files = 15,000 tokens saved (~60% reduction)

Vale Rules

Products (case-sensitive, error level)

• Tower → Seqera Platform (warning for legacy context)
• NextFlow/nextFlow/next-flow/NEXTFLOW → Nextflow
• wave → Wave
• fusion → Fusion
• studio → Studio, studios → Studios
• multi-qc/multiQC → MultiQC

Features (case-insensitive, error level)

• compute env/CE → compute environment (CE is warning)
• creds → credentials
• repo → repository
• config → configuration
• dropdown → drop-down
• work space/Workspace → workspace (Workspace is warning)
• API token → access token
• PAT → personal access token (warning for first-use context)

write-good Package

• Passive voice: suggestion level only
• Weasel words: disabled (sometimes needed)
• "There is": disabled (fine for technical docs)
• "So": disabled (fine for transitions)

Workflow

Local Development (optional Vale setup)
    ↓
1. Edit .md file in VSCode
    ↓
2. Vale shows inline errors as you type/save (if extension configured)
    ↓
3. Fix issues in real-time
    ↓
4. (Optional) Run: pre-commit run vale --all-files
    ↓
5. Commit → Standard hooks run (Vale does NOT run automatically)
    ↓
6. Push to GitHub
    ↓
PR Workflow (automatic)
    ↓
7. Vale (2 sec, free) + Claude agents (30 sec, tokens) run in parallel
    ↓
8. Vale posts terminology inline comments
    ↓
9. Claude agents post context-dependent inline comments
    ↓
10. Up to 60 inline suggestions shown (full list in artifact)

Critical VSCode Setup Note

Vale VSCode extension requires configuration in User Settings (~/Library/Application Support/Code/User/settings.json), not just workspace settings:

{
  "vale.valeCLI.path": "/opt/homebrew/bin/vale",
  "vale.valeCLI.config": "/Users/justine.geffen/work/docs/.vale.ini"
}

Workspace settings alone do not work reliably. See VALE_SETUP.md for complete details.

Testing

Validated:

• ✅ Vale CLI runs on single files and directories
• ✅ VSCode integration shows inline squiggles and Problems panel
• ✅ Pre-commit hook runs via manual invocation
• ✅ CI workflow updated with Vale job
• ✅ Product and feature rules catch common errors
• ✅ Context-dependent rules set to warnings
• ✅ Non-blocking everywhere (local and CI)

[netlify]

✅ Deploy Preview for seqera-docs ready!

Name	Link
🔨 Latest commit	c411394
🔍 Latest deploy log	https://app.netlify.com/projects/seqera-docs/deploys/6984ac1e7dfe7400078aeb74
😎 Deploy Preview	https://deploy-preview-1100--seqera-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify project configuration.