ci(docs): docs-gates workflow + DOCS_MAP generator (split 1/4 of #1317)

.github/workflows/docs-gates.yml

@@ -0,0 +1,36 @@
+# Documentation gates — MANDATORY, BLOCKING (required status check `docs-gates`).
+#
+#   1. Every component/domain has specs/PRD.md + specs/DESIGN.md — no docs, no pass.
+#   2. PRD/DESIGN follow the single canonical template — same structure everywhere.
+#   3. Artifacts are registered in cypilot/config/artifacts.toml — mapped to code.
+#   4. docs/DOCS_MAP.md is regenerated and committed — the map never goes stale.
+#
+# Exceptions only via docs/.docs-gate-waivers (reason + expiry, CODEOWNERS-reviewed;
+# expired waivers fail the gate). CI calls the same entrypoint developers run
+# locally (`make docs-check`) — shift-left, zero local/CI drift.
+
+name: Docs Gates
+
+on:
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  docs-gates:
+    name: docs-gates
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
+        with:
+          persist-credentials: false
+      - name: Documentation gate (presence, template conformance, code mapping)
+        run: python3 scripts/ci/docs_map.py --check
+      - name: DOCS_MAP.md must be regenerated and committed
+        run: |
+          git diff --exit-code docs/DOCS_MAP.md || {
+            echo "::error::docs/DOCS_MAP.md is stale. Run: make docs-map && commit."; exit 1; }

docs/.docs-gate-waivers

@@ -0,0 +1,7 @@
+# Documentation-gate waivers — the ONLY way past the docs gate.
+# Format:  <unit path> | <reason> | <expiry YYYY-MM-DD>
+# Expired waivers FAIL the gate by themselves. Reviewed via CODEOWNERS.
+docs/components/connectors | index of per-source specs; per-source PRD/DESIGN exist under each source dir — top-level specs to be added | 2026-07-31
+docs/domain/ingestion-data-flow | DESIGN-only domain (FULL traceability); PRD backlog item | 2026-07-31
+docs/components/frontend | PRD/DESIGN are placeholders not on the canonical template; rewrite + register scheduled | 2026-07-15
+docs/components/orchestrator | DESIGN not on canonical template; align + register scheduled | 2026-07-15