Xlorep DarkHelm
9b742a5a6d
## Summary This PR tightens repository quality enforcement around markdown and documentation. It adds `markdownlint` to the `cicd-checks` workflow, expands pre-commit coverage so markdown files are checked repo-wide, and cleans up the PP-58 documentation set to keep it aligned with the new policy. ## What changed - Added a `Markdownlint Check` entry to `.gitea/workflows/cicd-checks.yaml` - Added `markdownlint` to pre-commit and widened prettier coverage to include markdown files across the repo - Updated `README.md` to satisfy markdownlint line-length rules - Normalized the PP-58 documentation set: - `docs/DEPLOYABLE_RUNTIME_CONTRACT.md` - `docs/adr/ADR003-deployable_runtime_image_contract.md` - `docs/DEVELOPMENT.md` - `docs/CICD_MULTI_STAGE_BUILD.md` - `docs/CICD_TROUBLESHOOTING_GUIDE.md` - `docs/SECURE_DOCKER_CICD.md` ## Validation - `pre-commit run markdownlint --files README.md docs/DEPLOYABLE_RUNTIME_CONTRACT.md` - `pre-commit run prettier --files README.md docs/DEPLOYABLE_RUNTIME_CONTRACT.md` - Workflow YAML validation returned no errors ## Notes This change does not alter application runtime behavior. It only strengthens CI and documentation quality enforcement. Co-authored-by: copilotcoder <copilotcoder@darkhelm.org> Reviewed-on: #68
1.6 KiB
1.6 KiB
ADR001: Deterministic Runtime Policy
- Status: Accepted
- Date: 2026-05-16
Context
The backend must behave consistently across local development, CI, and production. Historically, floating dependency constraints and non-enforced runtime assumptions can introduce drift and hard-to-diagnose failures.
This branch introduced:
- Python 3.14 as the required runtime baseline
- Exact dependency pinning for backend runtime and development tooling
- Startup compatibility checks that fail fast when runtime policy is violated
- A compatibility endpoint for operational visibility
Decision
Adopt a deterministic backend runtime policy:
- Backend runtime is pinned to Python major/minor 3.14.
- Runtime dependencies are exact pinned versions.
- Application startup performs runtime policy validation and fails fast on mismatch.
- Compatibility status is exposed through an API endpoint for diagnostics.
- The lockfile is treated as the source of truth for reproducible dependency resolution.
Consequences
Positive:
- Reduced environment drift across dev/CI/prod
- Earlier and clearer failure mode for runtime mismatches
- Improved reproducibility and troubleshooting
Negative:
- More frequent explicit dependency maintenance updates
- Stricter upgrade process for Python/runtime packages
Alternatives Considered
- Floating dependency constraints with periodic updates
- Rejected due to non-deterministic installs and regression risk
- Runtime checks only in CI, not application startup
- Rejected because deployment/runtime drift can still bypass CI assumptions