ci(make): run the docs-integrity gate inside make ci

[bketelsen]

Summary

GitHub CI's docs-gate job (.github/workflows/test.yml) runs
make test-docs-check and node scripts/check-docs.mjs, but the local
make ci gate ran neither. An unindexed doc, a dead relative link, or a
broken conformance alias therefore passed the local gate and only surfaced
after a pull request was already open — the local signal was strictly weaker
than the one CI enforces.

This wires both invocations into the ci recipe, immediately after
verify-static so the cheap static checks still fail first and the docs gate
runs long before the coverage/E2E/race/cross-build steps. A focused contract
test (updex/makefile_ci_docs_gate_contract_test.go) reads the ci recipe out
of the Makefile and fails if either invocation is dropped, moved after the
CI gate passed line, or has its exit status swallowed (- prefix or a ||
fallback). It reuses the extractRecipe helper already in
updex/makefile_lint_guard_contract_test.go.

make ci behavior is otherwise unchanged; no CI workflow, permission, or
release path is touched. AGENTS.md's two make ci descriptions are updated so
they still enumerate what the target actually runs. Node >= 20 was already
listed under Prerequisites for the docs-integrity gate, so no new tool
requirement is introduced beyond making make ci depend on it.

Checks

• make fmt — code is formatted (gofmt -l on the new file is empty;
  make ci's verify: gofmt step passed)
• make ci — tidy, vet, gofmt, lint (.golangci.yml 2.13.1), the new
  docs-integrity steps, unit tests, the coverage floor
  (make test-coverage-check then make coverage-check), E2E, race tests,
  linux amd64/arm64 builds. Full run exit status 0:

==> verify: go.mod is tidy
==> verify: go vet
==> verify: gofmt
==> lint (golangci-lint 2.13.1)
==> docs-integrity checker self-test
node scripts/test-check-docs.mjs
test-check-docs: all assertions passed
==> docs integrity
ok   docs_index_coverage: 1.000 (required 1)
ok   link_integrity: 1.000 (required 1)
ok   symlink_resolution: 1.000 (required 1)
checked: 20 docs, 277 links, 9 symlinks
==> unit tests with coverage
...
==> cross-architecture build
==> CI gate passed

• CLI/e2e changes: not applicable — no CLI or e2e behavior changes. The
  E2E suite still ran green as part of make ci above.
• New or changed behavior has focused tests, including failure paths. The
  guard was mutation-tested against three regressions of the recipe:

### mutation 1: drop $(MAKE) test-docs-check
--- FAIL: TestMakefileCIRecipeRunsDocsIntegrityGate (0.00s)
    Makefile ci recipe must invoke `make test-docs-check` (the docs-gate CI job runs it)
### mutation 2: drop node scripts/check-docs.mjs
--- FAIL: TestMakefileCIRecipeRunsDocsIntegrityGate (0.00s)
    Makefile ci recipe must invoke `node scripts/check-docs.mjs` (the docs-gate CI job runs it)
### mutation 3: swallow the failure with || true
--- FAIL: TestMakefileCIRecipeRunsDocsIntegrityGate (0.00s)
    Makefile ci recipe swallows a docs-integrity failure with a `||` fallback: "\tnode scripts/check-docs.mjs || true"
### restored
ok  	github.com/frostyard/updex/updex	0.004s

Risk classification

• Tier 1: Low
• Tier 2: Moderate
• Tier 3: High

Rationale:

• The local make ci gate's composition changes (it now hard-requires Node and
  fails on a docs-integrity finding), so this is not a behavior-free
  documentation or test-only change; no product runtime behavior, security
  control, trust boundary, or release path is affected, and no
  protected_boundaries path in policies/agent-governance.json
  (.github/workflows/**, .goreleaser.yaml, .svu.yaml, sysext/**,
  systemd/**, download/**) is touched. The change only strengthens a gate —
  nothing in never_relax is weakened. Per the higher-plausible uncertainty
  rule in docs/risk-tiers.md, Tier 2 rather than Tier 1.

Docs housekeeping

• AGENTS.md updated for the workflow change (the two make ci
  descriptions and the pull-request checklist step). No README.md,
  docs/design/overview.md, or docs/specs/* change is needed — no
  product behavior changed.
• New docs started from their category's TEMPLATE.md and indexed in
  docs/README.md — not applicable, no new docs.
• New significant decision recorded as an ADR first — not applicable;
  this closes a gap against the existing docs-gate job rather than
  deciding anything new.
• Conformance aliases (ADR-0012) untouched.

Verification

• node scripts/check-docs.mjs green:

ok   docs_index_coverage: 1.000 (required 1)
ok   link_integrity: 1.000 (required 1)
ok   symlink_resolution: 1.000 (required 1)
checked: 20 docs, 277 links, 9 symlinks

and make test-docs-check green:

node scripts/test-check-docs.mjs
PASS: valid-fixture-passes
PASS: unindexed-category-document-fails
PASS: dead-relative-link-fails
PASS: broken-symlink-fails
PASS: escaping-symlink-fails
test-check-docs: all assertions passed

• Checked against the
  PR review rubric

[Copilot]

Pull request overview

Adds the docs-integrity checks to the canonical local CI gate.

Changes:

• Runs docs checker self-tests and integrity validation in make ci.
• Adds a contract test guarding both invocations and failure propagation.
• Updates contributor guidance.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
Makefile	Adds docs checks to ci.
updex/makefile_ci_docs_gate_contract_test.go	Guards the CI recipe contract.
AGENTS.md	Documents the strengthened gate.

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[bketelsen]

Confirmed, and the finding is correct on both counts at head 5ac9b99:

• docs/design/overview.md "CI and Releases" (lines 583-592) enumerates the make ci stages as verify-static -> coverage -> E2E -> race -> cross-build. grep -n 'docs-integrity\|check-docs' docs/design/overview.md returns nothing, so the file never mentions the two steps this PR inserts.
• docs/specs/pr-review-rubric.md:24 ("Build gate green") likewise enumerates make ci as tidy, vet, gofmt, golangci-lint, non-E2E unit tests, coverage gate, race, cross-build. The separate "Docs-integrity gate green" row names node scripts/check-docs.mjs but not as part of make ci, so the enumeration is now incomplete.

This is a patch change, not a mechanical cure, so it cannot be pushed under the pr-cure item that surfaced this thread (Snowcat refuses a cure whose patch identity moved). I have queued a bounded pr-cure-change proposal against this same branch to update both passages to match the ci: recipe in the Makefile — nothing else in either file. Leaving this thread unresolved until that lands.