ci: post-Phase-2-docs-overhaul cleanup of stale guards + missing config doc

CI run on the ecb8896 push surfaced two real failures rooted in the
2026-05-04 docs overhaul:

  1. G-3 env-docs-drift caught two phantom CERTCTL_* env vars I'd
     introduced in the Phase 4 follow-on connector pages
     (CERTCTL_CA_CERT_PATH_NEW in adcs.md was a placeholder I made
     up; CERTCTL_EJBCA_POLL_MAX_WAIT_SECONDS in ejbca.md does not
     exist in source). Both removed.

  2. QA-doc Part-count drift guard tried to grep
     docs/qa-test-guide.md and docs/testing-guide.md, both of which
     were renamed/deleted in Phase 2/Phase 5. The Part-count drift
     class died with testing-guide.md (Phase 5 prune dispersed its
     content); the seed-count drift class is still live but pointed
     at the wrong path.

Fixes:

- Removed the QA-doc Part-count drift guard from ci.yml (premise
  dead) plus its standalone scripts/qa-doc-part-count.sh peer.
- Retargeted the QA-doc seed-count drift guard from
  docs/qa-test-guide.md → docs/contributor/qa-test-suite.md (the
  Phase 2 target). Updated both ci.yml inline copy and
  scripts/qa-doc-seed-count.sh.
- Updated Makefile qa-stats: target to drop the testing-guide.md
  Parts metric (file is gone).
- Updated Makefile verify-docs: target to drop the part-count step.

G-3 was also failing in the second direction (env vars defined in
config.go but never documented anywhere). 16 vars surfaced —
features.md (deleted Phase 6) and testing-guide.md (deleted Phase 5)
had been their canonical home. Created
docs/reference/configuration.md as the new home: a compact
operator-facing env-var reference covering scheduler intervals, job
lifecycle, rate limiting, audit, deploy verify, database,
agent-side, and SCEP profile binding. Added to docs/README.md
Reference table.

Doc-side updates to qa-test-suite.md to reframe its references to
the deleted testing-guide.md (it's now self-contained: the
Part-by-Part Coverage Map IS the canonical Part inventory).

Cosmetic comment-only updates in ci.yml + scripts/ci-guards/*.sh +
scripts/dev-setup.sh to point at the new audience-organized doc
paths (docs/operator/security.md, docs/operator/tls.md,
docs/reference/architecture.md, etc.) instead of the pre-Phase-2
flat layout.

Verified: all 24 ci-guards/*.sh pass locally; qa-doc-seed-count.sh
clean. Net diff: 178 additions / 112 deletions across 13 files.
One file deleted (qa-doc-part-count.sh) and one file added
(docs/reference/configuration.md).

scripts/ci-guards/G-3-env-docs-drift.sh

@@ -101,7 +101,7 @@ if [ -n "$CONFIG_ONLY" ]; then
   echo "::error::G-3 regression: env var(s) defined in Go source but never documented:"
   echo "$CONFIG_ONLY"
   echo ""
-  echo "Add an entry to docs/features.md (or another canonical doc) so operators can find it."
+  echo "Add an entry to the canonical config doc (docs/reference/architecture.md or the per-connector pages under docs/reference/connectors/) (or another canonical doc) so operators can find it."
   exit 1
 fi
 echo "G-3 env-docs-drift: clean."

scripts/ci-guards/H-009-readme-jwt.sh

@@ -4,7 +4,7 @@
 # H-009 closed by Bundle D as verified-already-clean: at audit time
 # the README does NOT advertise JWT support (certctl does not ship
 # in-process JWT middleware; JWT/OIDC integration is via an
-# authenticating gateway, see docs/architecture.md "Authenticating-
+# authenticating gateway, see docs/reference/architecture.md "Authenticating-
 # gateway pattern"). This script grep-fails the build if README ever
 # re-introduces a sentence advertising JWT as a supported auth mode.
 # Pattern: "JWT" within ~6 words of "support|auth|enabled|mode" in
@@ -20,7 +20,7 @@ if grep -inE 'JWT.{0,40}(support|auth|enabled|mode|provider)' README.md \
   echo "::error::H-009 regression: README.md appears to advertise JWT auth support."
   echo "certctl does NOT ship in-process JWT middleware. JWT/OIDC"
   echo "integration is via an authenticating gateway — see"
-  echo "docs/architecture.md::Authenticating-gateway pattern."
+  echo "docs/reference/architecture.md::Authenticating-gateway pattern."
   echo "If you added a sentence about JWT to README, either remove"
   echo "it or rewrite it to point at the gateway pattern."
   exit 1

scripts/ci-guards/L-001-insecure-skip-verify.sh

@@ -2,11 +2,11 @@
 # scripts/ci-guards/L-001-insecure-skip-verify.sh
 #
 # L-001 audited every production InsecureSkipVerify=true call site
-# and documented the justification per site in docs/tls.md. This
+# and documented the justification per site in docs/operator/tls.md. This
 # script grep-fails the build if any new `InsecureSkipVerify: true`
 # lands in a non-test Go file without a `//nolint:gosec` comment
 # carrying the justification. Test files (_test.go) are exempt.
-# Updating the documented surface goes through the docs/tls.md
+# Updating the documented surface goes through the docs/operator/tls.md
 # table — net-new sites must be reasoned about before merge.
 
 set -e
@@ -32,7 +32,7 @@ if [ -n "$BAD" ]; then
   echo -e "$BAD"
   echo ""
   echo "Add a //nolint:gosec comment with justification on the same"
-  echo "or preceding line, AND add a row to the docs/tls.md table."
+  echo "or preceding line, AND add a row to the docs/operator/tls.md table."
   exit 1
 fi
 echo "L-001 insecure-skip-verify: clean."

scripts/ci-guards/U-2-plaintext-healthcheck.sh

@@ -11,7 +11,7 @@
 # HEALTHCHECK that targets `http://` against the certctl server
 # port.
 #
-# Comment lines and the docs/upgrade-to-tls.md:182 expected-to-
+# Comment lines and the docs/archive/upgrades/to-tls-v2.2.md:182 expected-to-
 # fail invariant ("plaintext is gone, expect Connection refused")
 # are intentionally exempt — we DO want the upgrade-doc string
 # `http://localhost:8443/health` to remain there, since it

scripts/dev-setup.sh

@@ -135,7 +135,7 @@ echo "  3. Test the API:"
 echo "     curl --cacert ./deploy/test/certs/ca.crt https://localhost:8443/health"
 echo ""
 echo "  4. Try the quick start guide:"
-echo "     cat docs/quickstart.md"
+echo "     cat docs/getting-started/quickstart.md"
 echo ""
 echo "  5. Access PgAdmin (optional):"
 echo "     make docker-up-dev"
@@ -150,6 +150,6 @@ echo "  make docker-logs   - View service logs"
 echo ""
 echo "For more information, see:"
 echo "  • README.md"
-echo "  • docs/architecture.md"
-echo "  • docs/quickstart.md"
+echo "  • docs/reference/architecture.md"
+echo "  • docs/getting-started/quickstart.md"
 echo ""

scripts/qa-doc-part-count.sh

@@ -1,27 +0,0 @@
-#!/usr/bin/env bash
-# scripts/qa-doc-part-count.sh
-#
-# Bundle P / Strengthening #6 — QA-doc Part-count drift guard.
-# Forces every PR that adds a Part to docs/testing-guide.md to keep
-# docs/qa-test-guide.md headline in sync.
-#
-# Per ci-pipeline-cleanup bundle Phase 11 / frozen decision 0.13:
-# moved out of CI (was in ci.yml) — operator runs via 'make verify-docs'
-# pre-tag. Protects docs-the-operator-reads, not anything the product
-# depends on; CI-blocking on every push was overkill.
-
-set -e
-DOC_PARTS=$(grep -oE '49 of [0-9]+ Parts' docs/qa-test-guide.md | grep -oE '[0-9]+' | tail -1)
-GUIDE_PARTS=$(grep -cE '^## Part [0-9]+:' docs/testing-guide.md)
-if [ -z "$DOC_PARTS" ]; then
-  echo "::error::Could not extract Part count from docs/qa-test-guide.md headline."
-  echo "  Expected pattern: '49 of <N> Parts'"
-  exit 1
-fi
-if [ "$DOC_PARTS" != "$GUIDE_PARTS" ]; then
-  echo "::error::DRIFT — qa-test-guide.md headline claims $DOC_PARTS Parts; testing-guide.md has $GUIDE_PARTS Parts."
-  echo "  Update docs/qa-test-guide.md to match. Bundle I patched this once;"
-  echo "  Bundle P added this guard so the drift cannot recur silently."
-  exit 1
-fi
-echo "qa-doc-part-count: clean ($DOC_PARTS == $GUIDE_PARTS)."

scripts/qa-doc-seed-count.sh

@@ -3,7 +3,7 @@
 #
 # Bundle P / Strengthening #6 — QA-doc seed-count drift guard.
 # Forces every PR that adds a seed row to migrations/seed_demo.sql
-# to keep docs/qa-test-guide.md::Seed Data Reference in sync.
+# to keep docs/contributor/qa-test-suite.md::Seed Data Reference in sync.
 #
 # Per ci-pipeline-cleanup bundle Phase 11 / frozen decision 0.13:
 # moved out of CI (was in ci.yml) — operator runs via 'make verify-docs'
@@ -13,19 +13,19 @@ set -e
 # Seed-cert count: agnostic to documented header format. The current
 # documented count lives in `### Certificates (32 total in ...` —
 # extract the first integer in that header.
-DOC_CERTS=$(grep -oE '### Certificates \([0-9]+' docs/qa-test-guide.md | grep -oE '[0-9]+' | head -1)
+DOC_CERTS=$(grep -oE '### Certificates \([0-9]+' docs/contributor/qa-test-suite.md | grep -oE '[0-9]+' | head -1)
 # Authoritative count: unique mc-* IDs in seed_demo.sql.
 SEED_CERTS=$(grep -oE 'mc-[a-z0-9_-]+' migrations/seed_demo.sql | sort -u | wc -l | tr -d ' ')
 if [ -z "$DOC_CERTS" ]; then
-  echo "::warning::Could not extract documented cert count from docs/qa-test-guide.md."
+  echo "::warning::Could not extract documented cert count from docs/contributor/qa-test-suite.md."
   echo "  Skipping cert-count drift check (header format may have changed)."
 elif [ "$DOC_CERTS" != "$SEED_CERTS" ]; then
-  echo "::error::DRIFT — qa-test-guide.md says $DOC_CERTS certs; seed_demo.sql has $SEED_CERTS unique mc-* IDs."
-  echo "  Update docs/qa-test-guide.md::Seed Data Reference to match."
+  echo "::error::DRIFT — qa-test-suite.md says $DOC_CERTS certs; seed_demo.sql has $SEED_CERTS unique mc-* IDs."
+  echo "  Update docs/contributor/qa-test-suite.md::Seed Data Reference to match."
   exit 1
 fi
 # Issuers: seed-table count vs doc claim.
-DOC_ISS=$(grep -oE '### Issuers \([0-9]+' docs/qa-test-guide.md | grep -oE '[0-9]+' | head -1)
+DOC_ISS=$(grep -oE '### Issuers \([0-9]+' docs/contributor/qa-test-suite.md | grep -oE '[0-9]+' | head -1)
 # Authoritative: unique iss-* IDs (close enough proxy; the issuers
 # table count IS the unique-ID count for this prefix).
 SEED_ISS=$(grep -oE 'iss-[a-z0-9_-]+' migrations/seed_demo.sql | sort -u | wc -l | tr -d ' ')
@@ -35,7 +35,7 @@ elif [ "$DOC_ISS" != "$SEED_ISS" ] && [ "$((SEED_ISS - DOC_ISS))" -gt 5 ]; then
   # Allow up to 5pp slack — iss-* IDs appear in audit_events and
   # other reference tables that aren't issuer-table rows. Drift
   # only flags when the spread grows large.
-  echo "::error::DRIFT — qa-test-guide.md says $DOC_ISS issuers; seed_demo.sql has $SEED_ISS unique iss-* IDs (spread > 5)."
+  echo "::error::DRIFT — qa-test-suite.md says $DOC_ISS issuers; seed_demo.sql has $SEED_ISS unique iss-* IDs (spread > 5)."
   exit 1
 fi
 echo "qa-doc-seed-count: clean."