Restore release workflow guards for CI stability

docs/README.md

@@ -49,12 +49,15 @@ Temporary analysis and summary documents from development work:
 - [Implementation Summary](summaries/IMPLEMENTATION_SUMMARY.md)
 - [PR Summary](summaries/PR_SUMMARY.md)
 - [Release Fix Summary](summaries/RELEASE_FIX_SUMMARY.md)
+- [Release Workflow Fix](summaries/RELEASE_WORKFLOW_FIX.md)
 - [Fixes Summary](summaries/FIXES_SUMMARY.md)
+- [Solution Summary](summaries/SOLUTION_SUMMARY.md)
 
 ### Handoffs
 
 LLM handoff notes for context preservation between sessions:
 - [Handoff Notes Guide](handoffs/README.md) - How to create and use handoff notes
-- [2026-01-22: Documentation Reorganization](handoffs/2026-01-22-documentation-reorganization.md) - This reorganization project
+- [2026-01-23: Documentation Structure Enforcement](handoffs/2026-01-23-documentation-enforcement.md) - Test to enforce doc placement policy
+- [2026-01-22: Documentation Reorganization](handoffs/2026-01-22-documentation-reorganization.md) - Documentation reorganization project
 
 See [.github/copilot-instructions.md](../.github/copilot-instructions.md) for the complete handoff note template.

docs/handoffs/2026-01-23-documentation-enforcement.md

@@ -0,0 +1,140 @@
+# Documentation Structure Enforcement
+
+**Date**: 2026-01-23  
+**Time**: 00:26 UTC  
+**Agent**: GitHub Copilot Agent (Claude-based)  
+**Context**: Follow-up to documentation reorganization (2026-01-22). User requested enforcement of documentation placement policy through automated tests and completion of handoff documentation.
+
+## Summary
+
+Added automated test to enforce documentation structure policy: only README.md, CLAUDE.md, and AGENT.md are allowed at repository root, all other markdown files must be under `/docs`. Completed the documentation reorganization by moving two remaining summary files (RELEASE_WORKFLOW_FIX.md and SOLUTION_SUMMARY.md) and creating this handoff note.
+
+## Key Decisions
+
+- **Test-based enforcement**: Implemented integration test rather than git hook or CI script
+  - **Rationale**: Integrates naturally with existing test suite, runs automatically in CI/CD, fails fast before merge, consistent with project testing practices
+
+- **Case-insensitive checking**: Test accepts README.md, readme.md, ReadMe.md, etc.
+  - **Rationale**: Prevents false positives on case-insensitive filesystems (macOS, Windows), matches common GitHub convention variations
+
+- **Minimal test design**: Single test function, clear violation messages, no external dependencies
+  - **Rationale**: Follows existing test patterns in `tests/cli_tests.rs` and `tests/parity_tests.rs`, easy to understand and maintain
+
+## Technical Details
+
+### Changes Made
+
+**New test file**: `tests/docs_structure.rs`
+- Reads repository root using `env!("CARGO_MANIFEST_DIR")`
+- Checks all `.md` files at root level
+- Allows only: `readme.md`, `claude.md`, `agent.md` (case-insensitive)
+- Reports violations with clear error message listing offending files
+
+**Documentation moves** (completed by user prior):
+- `RELEASE_WORKFLOW_FIX.md` → `/docs/summaries/RELEASE_WORKFLOW_FIX.md`
+- `SOLUTION_SUMMARY.md` → `/docs/summaries/SOLUTION_SUMMARY.md`
+- Updated `/docs/README.md` to reference these files in Summaries section
+
+**Handoff documentation**:
+- Created this handoff note: `/docs/handoffs/2026-01-23-documentation-enforcement.md`
+- Updated `/docs/README.md` Handoffs section to include this note
+
+### Implementation Details
+
+Test implementation approach:
+```rust
+// Use manifest dir to find repo root
+let root_path = Path::new(env!("CARGO_MANIFEST_DIR"));
+
+// Case-insensitive allowed list
+let allowed_files = ["readme.md", "claude.md", "agent.md"];
+
+// Check all .md files at root
+for entry in fs::read_dir(root_path) {
+    if filename_lower.ends_with(".md") {
+        if !allowed_files.contains(&filename_lower.as_str()) {
+            violations.push(filename_str);
+        }
+    }
+}
+```
+
+The test will fail with a clear message:
+```
+Found markdown files at repository root that should be in /docs:
+  - SOME_FILE.md
+  - ANOTHER_FILE.md
+
+Only README.md, CLAUDE.md, and AGENT.md are allowed at root.
+All other markdown files should be under /docs.
+```
+
+### Why This Approach Works
+
+1. **Automatic enforcement**: Runs with `cargo test`, CI/CD catches violations
+2. **Clear guidance**: Error message tells developers exactly what to fix
+3. **Future-proof**: New contributors can't accidentally add root-level docs
+4. **Zero maintenance**: No manual checks needed, test runs automatically
+
+## Testing
+
+**Manual verification**:
+- ✅ Test file created in `tests/docs_structure.rs`
+- ✅ Follows existing test structure and conventions
+- ✅ Uses `env!("CARGO_MANIFEST_DIR")` for repo root resolution
+- ✅ Case-insensitive comparison implemented
+- ✅ Clear assertion messages with violating file list
+
+**Not executed** (per user request):
+- Test suite run (`cargo test`)
+- Linters/formatters (`cargo clippy`, `cargo fmt`)
+
+## Future Considerations
+
+**Potential enhancements**:
+1. **Directory structure validation**: Could extend test to verify `/docs` subdirectory structure (development/, releases/, summaries/, handoffs/)
+2. **Link validation**: Test that all documentation links are valid and unbroken
+3. **Handoff note validation**: Test that handoff notes follow naming convention (YYYY-MM-DD-*.md)
+4. **Summary cleanup**: Archive old summary documents (6+ months) to `/docs/summaries/archive/`
+
+**Technical debt**:
+- None introduced
+
+## References
+
+**Related files**:
+- `tests/docs_structure.rs` - New test file
+- `tests/cli_tests.rs` - Existing test pattern reference
+- `/docs/handoffs/2026-01-22-documentation-reorganization.md` - Previous handoff note
+- `/docs/README.md` - Documentation index
+
+**Related decisions**:
+- Documentation reorganization (2026-01-22)
+- Handoff note system establishment (2026-01-22)
+
+## Handoff Context for Next Session
+
+**What's been done**:
+- Documentation structure enforcement test added
+- Final summary files moved to `/docs/summaries/`
+- Handoff documentation completed for this work
+
+**What works well**:
+- Test is minimal, clear, and follows project conventions
+- Policy is now automatically enforced via test suite
+- Documentation structure is complete and enforced
+
+**If you need to modify allowed root files**:
+- Edit the `allowed_files` array in `tests/docs_structure.rs`
+- Test will immediately reflect new policy
+- Remember to use lowercase names for case-insensitive matching
+
+**Known limitations**:
+- Test only checks `.md` files, not other documentation formats
+- Test doesn't validate `/docs` subdirectory structure
+- Test doesn't check for broken links in documentation
+
+**If something breaks**:
+- Test failure will clearly list violating files
+- Move violating files to appropriate `/docs` subdirectory
+- Run `cargo test` to verify fix

docs/summaries/IMPLEMENTATION_SUMMARY.md

@@ -56,7 +56,7 @@ remote: - Changes must be made through a pull request.
 ### `RELEASE_FIX_SUMMARY.md`
 - ✅ Created: Comprehensive documentation (6361 bytes)
 
-### `test-release-workflow.sh`
+### `scripts/tests/test-release-workflow.sh`
 - ✅ Created: Validation script with tests
 - ✅ Improved: Strict error handling (`set -euo pipefail`)
 - ✅ Uses: Package-specific jq queries
@@ -299,7 +299,7 @@ git push origin :refs/tags/v1.2.3
 - `.github/workflows/auto-release.yml` (major refactor)
 - `.github/workflows/release.yml` (added verification)
 - `RELEASE_FIX_SUMMARY.md` (new documentation)
-- `test-release-workflow.sh` (new test script)
+- `scripts/tests/test-release-workflow.sh` (new test script)
 - `IMPLEMENTATION_SUMMARY.md` (this file)
 
 ---

docs/summaries/PR_SUMMARY.md

@@ -58,7 +58,7 @@ All user-controlled inputs (PR titles, labels) now properly sanitized:
 ### Documentation
 - `RELEASE_FIX_SUMMARY.md` - Detailed technical explanation
 - `IMPLEMENTATION_SUMMARY.md` - Complete implementation overview
-- `test-release-workflow.sh` - Validation script
+- `scripts/tests/test-release-workflow.sh` - Validation script
 
 ## 🚀 Workflow After Fix