Merge branch 'master' into plan/github-issues-migration

Author: blalterman

.claude/branch-preservation.log

@@ -0,0 +1,4 @@
+{"plan_name": "compaction-hook-enhancement", "timestamp": "2025-08-19T12:00:00Z", "preserved_branches": ["plan/compaction-hook-enhancement"], "note": "Branches preserved for auditing purposes - DO NOT DELETE"}
+{"plan_name": "hook-system-enhancement", "timestamp": "2025-08-19T12:30:00Z", "preserved_branches": ["plan/hook-system-enhancement"], "note": "Branches preserved for auditing purposes - Plan abandoned as over-engineered - DO NOT DELETE"}
+{"plan_name": "readthedocs-automation", "timestamp": "2025-08-19T16:42:31.919241", "preserved_branches": [], "note": "Branches preserved for auditing purposes - DO NOT DELETE"}
+Sun Aug 24 19:32:01 EDT 2025: Archived python-310-migration plan from plan/python-310-migration branch (preserved) to plans/completed/python-310-migration/

.claude/compacted_state.md

@@ -1,10 +1,11 @@
-# Compacted Context State - 2025-08-22T05:25:09Z
+# Compacted Context State - 2025-08-22T05:27:59Z
 
 ## Compaction Metadata
-- **Timestamp**: 2025-08-22T05:25:09Z
-- **Branch**: plan/github-issues-migration
-- **Plan**: github-issues-migration
-- **Pre-Compaction Context**: ~8,565 tokens (1,808 lines)
+- **Timestamp**: 2025-08-22T05:27:59Z
+- **Branch**: plan/pr-270-doc-validation-fixes
+- **Plan**: pr-270-doc-validation-fixes
+
+- **Pre-Compaction Context**: ~8,491 tokens (1,799 lines)
 - **Target Compression**: medium (35% reduction)
 - **Target Tokens**: ~5,567 tokens
 - **Strategy**: medium compression with prose focus
@@ -25,105 +26,120 @@
   - **Final estimate**: 8,565 tokens
 
 ## Git State
-### Current Branch: plan/github-issues-migration
-### Last Commit: cf5dc41 - Merge master with scope audit system and enhanced hooks (blalterman, 23 seconds ago)
+### Current Branch: plan/pr-270-doc-validation-fixes
+### Last Commit: dbe38f3 - refactor: right-size documentation validation framework (blalterman, 35 seconds ago)
 
 ### Recent Commits:
 ```
-cf5dc41 (HEAD -> plan/github-issues-migration) Merge master with scope audit system and enhanced hooks
-4f9a93e (master) feat(scope-audit): add comprehensive plan scope validation system
-aeb1fe3 (origin/master, origin/HEAD) Merge pull request #269 from blalterman/plan/tests-audit
-bf18bff (origin/plan/tests-audit, plan/tests-audit) refactor(tests-audit): consolidate artifacts into plan directory
-65383f7 docs(tests): complete plan status reconciliation with implementation history
+dbe38f3 (HEAD -> plan/pr-270-doc-validation-fixes) refactor: right-size documentation validation framework
+11ab725 fix: resolve PR #270 check failures for documentation validation
+d58af82 feat: create comprehensive plan for PR #270 documentation validation fixes
+f6b0655 (origin/plan/documentation-code-audit, plan/fix-pr-checks-right-size-docs-validation, plan/documentation-code-audit) docs: complete Phase 8 closeout for documentation code audit
+685bfd6 docs: complete Phase 7 comprehensive reporting and documentation
 ```
 
 ### Working Directory Status:
 ```
-Clean working directory
-```
+M .claude/compacted_state.md
+ D automated_validation_hooks.py
+ D doctest_execution_report.json
+ D doctest_fixtures.py
+ D doctest_guidelines.md
+ D doctest_physics_validator.py
+ D final_validation_report.json
+ D pytest_doctest_config.py
+... and 3 more files
+
 
 ### Uncommitted Changes Summary:
 ```
-No uncommitted changes
-```
+.claude/compacted_state.md      |  38 +--
+ automated_validation_hooks.py   | 472 ---------------------------------
+ doctest_execution_report.json   | 113 --------
+ doctest_fixtures.py             | 504 -----------------------------------
+ doctest_guidelines.md           | 454 --------------------------------
+ doctest_physics_validator.py    | 569 ----------------------------------------
+ final_validation_report.json    | 256 ------------------
+ pytest_doctest_config.py        | 392 ---------------------------
+ validation_report_template.json | 214 ---------------
+ validation_results.json         | 376 --------------------------
+ validation_workflow_guide.md    | 411 -----------------------------
+ 11 files changed, 10 insertions(+), 3789 deletions(-)
 
 ## Critical Context Summary
 
 ### Active Tasks (Priority Focus)
-- **Phase 1: Foundation & Label System** (Est: 6-8 hours) - GitHub labels setup and issue templates creation
-- **Phase 2: Migration Tool Complete Rewrite** (Est: 8-10 hours) - PropositionsAwareMigrator implementation
-- **Phase 3: CLI Integration & Automation** (Est: 4-5 hours) - gh CLI scripts and workflow automation
-- **Phase 4: Validated Migration** (Est: 4-5 hours) - Migrate existing plans with validation
-- **Phase 5: Documentation & Training** (Est: 2-4 hours) - Update documentation and team training
+- **Phase 1: Critical PR Check Fixes** (Est: 2-3 hours) - Fix GitHub Actions v3→v4, doc8 linting, ReadTheDocs failures
+- **Phase 2: Framework Right-Sizing** (Est: 2-3 hours) - Consolidate 3000→300 lines validation code, archive over-engineering
+- **Phase 3: Sustainable Documentation Process** (Est: 1-2 hours) - Create minimal validation, update guidelines
+- **Phase 4: Closeout and Migration** (Est: 1 hour) - Verify functionality, create transition guide
+- All PR #270 checks passing (GitHub Actions, doc8, ReadTheDocs)
 
 ### Recent Key Decisions
 - No recent decisions captured
 
 ### Blockers & Issues
-⚠️ Complete the GitHub Issues migration with comprehensive documentation updates, team training materials, and workflow transition support. Ensure seamless adoption of the new GitHub-native planning system.
-⚠️ With successful migration completed, this final phase ensures team adoption and long-term success. The documentation must reflect the new GitHub Issues workflow while training materials enable confident team transition from local plans to GitHub-native planning.
-⚠️ - [ ] **Update CLAUDE.md workflow section** (Est: 45 min) - Complete GitHub Issues workflow documentation
+⚠️ - [ ] Troubleshooting common validation issues
 
 ### Immediate Next Steps
-➡️ ### Next Actions
-➡️ - [ ] **Prepare team communication** (Est: 15 min) - Migration success announcement and next steps
-➡️ ### Next Actions
+➡️ ## Next Phase
 
 ## Session Context Summary
 
-### Active Plan: github-issues-migration
+### Active Plan: pr-270-doc-validation-fixes
 ## Plan Metadata
-- **Plan Name**: GitHub Issues Migration with Propositions Framework
-- **Created**: 2025-08-19
-- **Branch**: plan/github-issues-migration
-- **Implementation Branch**: feature/github-issues-migration
+- **Plan Name**: PR #270 Documentation Validation Fixes and Framework Right-Sizing
+- **Created**: 2025-08-21
+- **Branch**: plan/pr-270-doc-validation-fixes
+- **Implementation Branch**: feature/pr-270-doc-validation-fixes
 - **PlanManager**: UnifiedPlanCoordinator
 - **PlanImplementer**: UnifiedPlanCoordinator
 - **Structure**: Multi-Phase
-- **Total Phases**: 5
+- **Total Phases**: 4
 - **Dependencies**: None
-- **Affects**: plans/, .claude/hooks/, .claude/scripts/, CLAUDE.md, .github/ISSUE_TEMPLATE/, issues_from_plans.py
-- **Estimated Duration**: 24-32 hours
+- **Affects**: .github/workflows/, .readthedocs.yaml, scripts/doc_validation/, docs/, tests/
+- **Estimated Duration**: 6-8 hours
 - **Status**: Planning
 
 
 ### Plan Progress Summary
-- Plan directory: plans/github-issues-migration
-- Last modified: 2025-08-21 21:06
+- Plan directory: plans/pr-270-doc-validation-fixes
+- Last modified: 2025-08-21 21:04
 
 ## Session Resumption Instructions
 
 ### 🚀 Quick Start Commands
 ```bash
 # Restore session environment
-git checkout plan/github-issues-migration
-cd plans/github-issues-migration && ls -la
+git checkout plan/pr-270-doc-validation-fixes
+cd plans/pr-270-doc-validation-fixes && ls -la
+git status
 pwd  # Verify working directory
 conda info --envs  # Check active environment
 ```
 
 ### 🎯 Priority Actions for Next Session
-1. Review plan status: cat plans/github-issues-migration/0-Overview.md
-2. Continue: **Phase 1: Foundation & Label System** (Est: 6-8 hours) - GitHub labels setup and issue templates creation
-3. Continue: **Phase 2: Migration Tool Complete Rewrite** (Est: 8-10 hours) - PropositionsAwareMigrator implementation
-4. Resolve: Complete the GitHub Issues migration with comprehensive documentation updates, team training materials, and workflow transition support. Ensure seamless adoption of the new GitHub-native planning system.
-5. Resolve: With successful migration completed, this final phase ensures team adoption and long-term success. The documentation must reflect the new GitHub Issues workflow while training materials enable confident team transition from local plans to GitHub-native planning.
+1. Review plan status: cat plans/pr-270-doc-validation-fixes/0-Overview.md
+2. Continue: **Phase 1: Critical PR Check Fixes** (Est: 2-3 hours) - Fix GitHub Actions v3→v4, doc8 linting, ReadTheDocs failures
+3. Continue: **Phase 2: Framework Right-Sizing** (Est: 2-3 hours) - Consolidate 3000→300 lines validation code, archive over-engineering
+4. Resolve: - [ ] Troubleshooting common validation issues
+5. Review uncommitted changes and decide on commit strategy
 
 ### 🔄 Session Continuity Checklist
 - [ ] **Environment**: Verify correct conda environment and working directory
-- [ ] **Branch**: Confirm on correct git branch (plan/github-issues-migration)
+- [ ] **Branch**: Confirm on correct git branch (plan/pr-270-doc-validation-fixes)
 - [ ] **Context**: Review critical context summary above
-- [ ] **Plan**: Check plan status in plans/github-issues-migration
-- [ ] **Changes**: No uncommitted changes to review
+- [ ] **Plan**: Check plan status in plans/pr-270-doc-validation-fixes
+- [ ] **Changes**: Review uncommitted changes
 
 ### 📊 Efficiency Metrics
 - **Context Reduction**: 35.0% (8,565 → 5,567 tokens)
 - **Estimated Session Extension**: 21 additional minutes of productive work
 - **Compaction Strategy**: medium compression focused on prose optimization
 
 ---
-*Automated intelligent compaction - 2025-08-22T05:25:09Z*
+*Automated intelligent compaction - 2025-08-22T05:27:59Z*
 
 ## Compaction File
-Filename: `compaction-2025-08-22-052509-35pct.md` - Unique timestamp-based compaction file
+Filename: `compaction-2025-08-22-052759-35pct.md` - Unique timestamp-based compaction file
 No git tags created - using file-based state preservation

.github/workflows/branch-protection.yml

@@ -32,7 +32,7 @@ jobs:
           enforce_admins: ${{ github.event.inputs.enforce_admins }}
           required_status_checks: |
             CI (ubuntu-latest, 3.11)
-            CI (ubuntu-latest, 3.8)
+            CI (ubuntu-latest, 3.10)
             Documentation / build
             Security Scan / security
           required_approving_review_count: 1

.github/workflows/ci.yml

@@ -11,12 +11,10 @@ jobs:
     strategy:
       matrix:
         os: [ubuntu-latest, macos-latest, windows-latest]
-        python-version: ['3.8', '3.9', '3.10', '3.11', '3.12']
+        python-version: ['3.10', '3.11', '3.12']
         # Exclude problematic combinations if needed
         exclude:
-          # Exclude Windows + Python 3.8 if there are known issues
-          # - os: windows-latest
-          #   python-version: '3.8'
+          # No exclusions needed for Python 3.10+ support
       fail-fast: false  # Continue testing other combinations on failure
 
     runs-on: ${{ matrix.os }}
@@ -29,7 +27,7 @@ jobs:
           python-version: ${{ matrix.python-version }}
 
       # Add caching for faster builds
-      - uses: actions/cache@v3
+      - uses: actions/cache@v4
         with:
           path: |
             ~/.cache/pip