ci: close stale auto-docs PRs

[devin-ai-integration]

Pull Request Description

Summary

Adds a 7-day stale check to auto-docs.yml so an unchanged open auto-docs/update PR is closed before the workflow proceeds to generate and push fresh documentation updates.

Type of Change

• Bug fix (non-breaking change that fixes an issue)
• New feature (non-breaking change that adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Security fix (addresses a security vulnerability)
• Performance improvement (improves performance without changing functionality)
• Documentation update (changes to documentation only)
• Code refactoring (improves code quality without changing functionality)
• Test enhancement (adds or improves tests)
• Dependency update (updates dependencies)

Related Issues

Relates to #288

Motivation and Context

Why is this change required?

The v3.1.0 hygiene instructions asked to close PR #288 if auto-docs.yml is producing nothing actionable and to add a 7-day stale check to that workflow.

What problem does it solve?

It prevents old automated documentation PRs from staying open indefinitely when the branch is not being refreshed with actionable changes.

Cryptographic Impact

Security Impact Assessment

• No cryptographic security impact
• Adds new cryptographic primitive (requires extensive review)
• Modifies existing cryptographic operation (requires security analysis)
• Changes key management approach
• Affects multiple security layers
• Performance optimization only (no security changes)

Standards Compliance

• NIST FIPS 202 (SHA-3)
• NIST FIPS 204 (Dilithium)
• NIST SP 800-108 (Key Derivation)
• RFC 2104 (HMAC)
• RFC 5869 (HKDF)
• RFC 8032 (Ed25519)
• RFC 3161 (Timestamps)
• No standards affected

Academic References

N/A — no cryptographic construction changes.

Security Analysis

Classical Security: No cryptographic implementation changes.

Quantum Security: No PQC implementation or parameter changes.

Security Impact: Workflow maintenance only.

Implementation Details

Changes Made

1. Granted issues: write so the workflow can leave a close comment on stale auto-docs PRs.
2. Added a Close stale auto-docs PR step that checks the open auto-docs/update PR's updatedAt timestamp.
3. Closes that PR with an explanatory comment when it has been unchanged for more than 7 days.

Technical Approach

Use gh pr list to inspect the current auto-docs PR and gh pr close to close stale output before the Sphinx build/update branch step runs. This leaves normal no-change behavior intact.

Breaking Changes

Breaking Changes:

• None
• Yes (describe below)

Migration Path:
N/A.

Testing

Test Coverage

• Unit tests added/updated
• Integration tests added/updated
• Test coverage maintained or improved
• All tests pass locally

Testing Performed

Environment:

• Python version(s): Python 3.12 local venv
• Operating System: Linux
• PQC backend: [ ] Native C library [x] None

Test Cases:

1. Parsed .github/workflows/auto-docs.yml with PyYAML.
2. Verified permissions.issues == write.
3. Verified the Close stale auto-docs PR workflow step exists.
4. git diff --check.

Known Test Vectors

• Tested against official NIST test vectors
• Tested against IETF RFC test vectors
• No official test vectors available

Code Quality

Code Quality Checks

• Code follows PEP 8 style guidelines
• All functions have type hints
• All functions have comprehensive docstrings
• No security warnings from linters (Bandit, etc.)
• Black formatting applied (black .)
• Ruff linting passed (ruff check .)
• Type checking passed (mypy ama_cryptography/)

Documentation Updates

• README.md updated
• SECURITY.md updated (if security affected)
• IMPLEMENTATION_GUIDE.md updated (if deployment affected)
• CHANGELOG.md updated
• Inline code comments added for complex logic
• Docstrings include academic citations (if applicable)

Backwards Compatibility

Compatibility Assessment

• Fully backwards compatible
• Backwards compatible with deprecation warnings
• Breaking changes with migration path
• Major version bump required

Deprecation Notices

Deprecated Features:

• None

Deprecation Timeline:

• N/A

Performance Impact

Performance Analysis

Benchmarks:
N/A — workflow metadata only.

Impact:

• No performance impact
• Performance improvement
• Slight performance degradation
• Significant performance impact

Link to Devin session: https://app.devin.ai/sessions/380c3bcb95034d1f83fb66062f20e8cf
Requested by: @Steel-SecAdv-LLC

[devin-ai-integration]

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

• Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
• Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

• Disable automatic comment and CI monitoring

[devin-ai-integration]

Closing as superseded by merged PR #301. The 7-day stale auto-docs workflow check is already present on main via #301.