fix: Address CodeRabbit security and correctness feedback on documentation workflow #1386

Summary

CodeRabbit identified security and correctness issues in the consolidated documentation.yml workflow (PR #1317). This issue tracks fixes for:

Issues Identified

Security

• Overly broad workflow permissions (scope to individual jobs)
• Missing persist-credentials flags on checkout steps
• Shell script variable handling security

Correctness

• Maintenance report misrepresents outcomes (shows success when scripts fail)
• README resolver over-includes root README on every change
• Documentation lacks clarity on output format (comma-separated vs space-separated)

Solution

Branch: fix/workflows-documentation-security-hardening

Changes Included

1. Job-scoped permissions — Remove overly broad top-level permissions; scope to audit, regenerate, maintain jobs
2. persist-credentials flags — Set to false for read-only (audit), true for write operations
3. Maintenance report accuracy — Track individual step outcomes; display actual success/failure status
4. README resolver optimization — Only add root README when subdirectory files change
5. Enhanced documentation — Comments explaining output format, execFileSync security rationale

Related Issues

• Epic: feat: Consolidate 31 GitHub workflows for efficiency and maintainability #1227 (GitHub Workflows Consolidation Initiative)
• PR refactor(workflows): consolidate documentation & validation workflows (Phase 2) #1313: Documentation consolidation implementation
• PR chore(workflows): cleanup legacy README workflows (Phase 2.4) #1317: Legacy workflow cleanup (merged)
• Issue #2.3: Integration Testing — Documentation Workflows #1309: Phase 2.3 Integration Testing
• Issue #2.4: Cleanup Old Workflows — Disable & Delete #1310: Phase 2.4 Cleanup (resolved)

Definition of Ready (DoR)

• Bug is reproducible and clearly described
• Steps to reproduce written
• Environment details provided
• Linked to existing issues/PRs (if any)
• Ready for triage

Definition of Done (DoD)

• Bug confirmed and reproducible
• Fix implemented and tested
• Follows coding standards
• Changelog entry prepared for PR (CHANGELOG.md)
• Security: job-scoped permissions and persist-credentials applied
• Performance: no adverse impact introduced
• QA performed
• Linked issue closed

Related issues: #1227, #1309, #1310, #1317