docs: add gauge-repo engineering best-practices audit

[juilichormole]

Summary

Adds the gauge-repo engineering best-practices audit for heimdall at docs/engineering-best-practices-audit.md (data-platform catalog batch).

• Adjusted compliance: 40.8% (15 Met, 10 Partial, 24 Gap, 0 N/A of 49 items)
• Critical gates: RED — required CI (item 16), integration tests (item 24), and scoped-per-environment secrets (item 40) are Partial
• Top recommendations:
  1. [S] Partial — required CI: add a required_status_checks rule to the main + releases ruleset referencing the Build and Test job
  2. [M] Partial — integration tests: add an integration target that boots docker compose, runs deploydb, and drives /api/v1/job end-to-end
  3. [S] Partial — scoped secrets per environment: move DockerHub push into a production GitHub Environment and document AWS_* env-var scoping

Documentation only — no code changes.

---

Requested by: juili.chormole@pattern.com

[Copilot]

🟡 Changes recommended

The new document contains a broken in-repo reference (references/best-practices.md) that should be corrected or removed.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds a new engineering best-practices audit document for the heimdall repository under docs/, capturing the repo profile, scorecard, per-category checklist results, and prioritized recommendations.

Changes:

• Introduced a structured audit report with compliance scoring and critical-gate status.
• Added per-category tables (Documentation/Guardrails/Testing/Environment/Agent dispatch) with evidence and recommendations.
• Included a prioritized recommendation list and “beyond the checklist” notes.

File summaries

File	Description
docs/engineering-best-practices-audit.md	New audit document summarizing best-practices compliance, evidence, and prioritized remediation steps for the repo.

Review details

• Files reviewed: 1/1 changed files
• Comments generated: 1
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[amitiwari1411]

Approving: docs-only addition of engineering best-practices audit report.