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.9 KiB
1.9 KiB
ADR003: Deployable Runtime Image Contract Boundaries
- Status: Accepted
- Date: 2026-06-19
Context
The repository has both deployable runtime artifacts and CI/development tooling artifacts. Without an explicit boundary, non-runtime concerns can drift into deployable images, making runtime behavior less predictable and increasing artifact complexity.
Issue PP-58 requires a clear, approved contract for minimal backend and frontend deployable images, including health and startup behavior and explicit exclusion of non-runtime tooling classes.
Decision
Adopt a canonical deployable runtime contract at:
docs/DEPLOYABLE_RUNTIME_CONTRACT.md
The contract defines, for backend and frontend deployable images:
- Runtime artifact boundaries (final image intent and payload).
- Runtime entrypoint and exposed ports.
- Runtime health and startup behavior expectations.
- Runtime environment variable contract.
- Disallowed non-runtime tooling classes in final deployable images.
Scope guardrails for PP-58:
- Documentation and architectural decision codification only.
- No CI workflow rewiring in this issue.
- No test execution redesign in this issue.
- Enforcement automation deferred to follow-up work under epic #66.
Consequences
Positive:
- Deployable image intent is explicit and auditable.
- Future tickets can implement automated checks against a stable policy.
- Reduced ambiguity between runtime artifacts and CI/development environments.
Negative:
- Requires ongoing documentation maintenance when runtime contracts evolve.
- Drift can still occur if future changes bypass policy review.
Alternatives Considered
- Rely on Dockerfiles only as implicit contract.
- Rejected: too easy for intent drift and inconsistent interpretation.
- Enforce contract immediately in CI without documentation-first baseline.
- Rejected: increases implementation risk without agreed policy language.