docs: remove internal engineering docs; docs must be tool- or story-relevant

Operator policy: docs in the public repo must help (a) a user deploying certctl or (b) the product story. Internal engineering process documentation belongs in cowork/ scratchpads or in git commit history, not docs/. Removed (docs/contributor/, 8 files, 2,323 lines): - release-sign-off.md — internal release-day checklist - ci-pipeline.md — what runs in CI (internal) - ci-guards.md — what the guards are (internal) - testing-strategy.md — internal testing strategy - qa-test-suite.md — internal QA reference (445 lines) - qa-prerequisites.md — internal QA setup - gui-qa-checklist.md — manual GUI QA checklist - test-environment.md — 1,103-line redundant with docs/getting-started/quickstart.md + docs/getting-started/advanced-demo.md Removed supporting script: - scripts/qa-doc-seed-count.sh — CI guard for the deleted qa-test-suite.md seed-data table Cross-reference cleanup: - README.md: dropped the Contributor audience row + footer pointer to docs/contributor/. - Makefile: dropped `verify-docs` target + qa-stats comment refs. - .github/workflows/ci.yml: dropped the QA-doc seed-count drift CI step + dead comment refs. - docs/reference/cli.md: repointed qa-prerequisites.md → quickstart.md. - docs/operator/performance-baselines.md: dropped ci-pipeline.md cross-ref. - scripts/ci-guards/README.md: dropped the 'Guards explicitly NOT here' section that referenced the deleted QA-doc guards. G-3 env-docs-drift guard improvements (a real consequence: deleting the contributor docs surfaced that some env vars only had a home there). Refit the guard to the new doc topology: - Defined-scan widened from `config.go + cmd/*` to all of `cmd/ + internal/` (production code), excluding `*_test.go` — catches service-layer env vars like CERTCTL_STEPCA_ROOT_CERT and CERTCTL_ZEROSSL_EAB_URL that were previously invisible to the guard. - Docs-scan widened to include deploy/ENVIRONMENTS.md (the canonical env-var inventory table — should have been in scope from day one). Kept narrow to README + docs/ + deploy/helm/ + ENVIRONMENTS.md to avoid pulling in compose/test fixtures. - ALLOWED filter now applies to both DOCS_ONLY and CONFIG_ONLY directions, so dynamic per-profile dispatch surfaces (CERTCTL_SCEP_PROFILE_<NAME>_*, CERTCTL_EST_PROFILE_<NAME>_*, CERTCTL_QA_*) don't need static doc entries. - Added CERTCTL_SCEP_PROFILE_[A-Z_]+ and CERTCTL_EST_PROFILE_[A-Z_]+ to ALLOWED for the same reason. deploy/ENVIRONMENTS.md: added CERTCTL_ZEROSSL_EAB_URL row — real operator override (overrides the ZeroSSL EAB-credentials endpoint; read at internal/connector/issuer/acme/acme.go:372) that was defined in Go source but never documented. G-3 caught it after the defined-scan widened. scripts/ci-guards/S-1-hardcoded-source-counts.sh: removed dead WORKSPACE-CHANGELOG.md allowlist entry (the file was deleted in the prior workspace cleanup). Verified: All 35 scripts/ci-guards/*.sh green (FAIL=0). No remaining references to docs/contributor/ or qa-doc-seed-count in tracked files.
2026-06-07 17:02:43 +00:00 · 2026-05-13 02:44:27 +00:00
parent 57b539c378
commit 0161bb201c
18 changed files with 29 additions and 2464 deletions
@@ -24,14 +24,19 @@
 # cat-g-* for closure rationale.

 set -e
-# Defined: config.go + agent + cli + mcp-server + server cmds + test fixtures + ACME DNS export
+# Defined: any CERTCTL_* env-var name appearing in production Go sources
+# (cmd/ + internal/, excluding *_test.go) plus the ACME DNS-01 script-
+# export surface. Test files use `t.Setenv` on env-var names that aren't
+# necessarily operator config; harness-only names should not flag.
 {
-  grep -nE '"CERTCTL_[A-Z_]+"' internal/config/config.go | sed -E 's/.*"(CERTCTL_[A-Z_]+)".*/\1/'
-  grep -rhoE '"CERTCTL_[A-Z_]+"' cmd/agent/*.go cmd/cli/*.go cmd/mcp-server/*.go cmd/server/*.go 2>/dev/null | sed -E 's/"(CERTCTL_[A-Z_]+)"/\1/'
-  grep -rhoE 'CERTCTL_[A-Z_]+' deploy/test/qa_test.go internal/connector/issuer/acme/dns.go 2>/dev/null
+  grep -rhoE '"CERTCTL_[A-Z_]+"' --include='*.go' --exclude='*_test.go' cmd/ internal/ 2>/dev/null | sed -E 's/"(CERTCTL_[A-Z_]+)"/\1/'
+  grep -rhoE 'CERTCTL_[A-Z_]+' internal/connector/issuer/acme/dns.go 2>/dev/null
 } | grep -E '^CERTCTL_' | sort -u > /tmp/g3-defined.txt
-# Documented: README + docs + helm
-grep -rhoE '\bCERTCTL_[A-Z_]+\b' README.md docs/ deploy/helm/ 2>/dev/null | sort -u > /tmp/g3-docs.txt
+# Documented: README + docs + helm + deploy/ENVIRONMENTS.md.
+# (ENVIRONMENTS.md is the canonical env-var inventory; the rest of
+# deploy/ contains compose/test fixtures whose env-var mentions are
+# implementation noise, not operator documentation.)
+grep -rhoE '\bCERTCTL_[A-Z_]+\b' README.md docs/ deploy/helm/ deploy/ENVIRONMENTS.md 2>/dev/null | sort -u > /tmp/g3-docs.txt
 # Allowlist of env vars documented as external integration contracts.
 # Each entry justifies itself in one line; if you add to this list,
 # add the justification.
@@ -59,6 +64,8 @@ CERTCTL_AUDIT_EXCLUDE_PATHS|
 CERTCTL_TLS_|
 CERTCTL_TLS_INSECURE_SKIP_VERIFY|
 CERTCTL_SCEP_|
+CERTCTL_SCEP_PROFILE_[A-Z_]+|
+CERTCTL_EST_PROFILE_[A-Z_]+|
 CERTCTL_SERVER_CA_BUNDLE_PATH|
 CERTCTL_SERVER_TLS_INSECURE_SKIP_VERIFY|
 CERTCTL_QA_[A-Z_]+|
@@ -89,7 +96,11 @@ CERTCTL_RATE_LIMIT_
 # the documented external contracts here.
 ALLOWED_FLAT=$(echo "$ALLOWED" | tr -d '\n ')
 DOCS_ONLY=$(comm -13 /tmp/g3-defined.txt /tmp/g3-docs.txt | grep -vE "$ALLOWED_FLAT" || true)
-CONFIG_ONLY=$(comm -23 /tmp/g3-defined.txt /tmp/g3-docs.txt || true)
+# Apply the same allowlist to the CONFIG_ONLY direction so dynamic
+# per-profile dispatch surfaces (CERTCTL_SCEP_PROFILE_<NAME>_*, etc.)
+# aren't flagged as "defined but never documented" — they can't all
+# be enumerated in a static doc.
+CONFIG_ONLY=$(comm -23 /tmp/g3-defined.txt /tmp/g3-docs.txt | grep -vE "$ALLOWED_FLAT" || true)
 if [ -n "$DOCS_ONLY" ]; then
  echo "::error::G-3 regression: env var(s) mentioned in docs but not defined in Go source AND not in the documented integration-surface allowlist:"
  echo "$DOCS_ONLY"
@@ -41,8 +41,6 @@ Current helpers:
  `PR_NUMBER` + `GH_TOKEN` env from the go-build-and-test job
 - `scripts/check-coverage-thresholds.sh` — consumes `coverage.out`
  + `.github/coverage-thresholds.yml`
- `scripts/qa-doc-part-count.sh` + `scripts/qa-doc-seed-count.sh` —
-  invoked via `make verify-docs` pre-tag, not in CI

 ## Adding a new guard

@@ -97,12 +95,6 @@ The cold-DB compose smoke (post-v2.1.0 / item-6) is NOT a script in this directo

 The fourth Bundle artifact (`internal/ciparity/`) is Go tests, not shell guards — runs under the standard Go test step. Pins the MCP tool catalogue floor + naming convention; reports CLI/MCP/OpenAPI surface counts as a trend metric.

-## Guards explicitly NOT here
-
- **`QA-doc Part-count drift`** + **`QA-doc seed-count drift`** — these
-  protect docs-the-operator-reads, not anything the product depends on.
-  Moved to `make verify-docs` (operator runs pre-tag, not on every push).
-  See the ci-pipeline-cleanup spec, Phase 11.

 ## Running the full set locally

@@ -14,8 +14,7 @@
 #
 # Allowed surfaces: demo-fixture prose in README ("32
 # certificates" — those are seed_demo.sql facts, not live
-# source counts), historical-milestone counts in
-# WORKSPACE-CHANGELOG.md, the testing-guide example phrasing
+# source counts), the testing-guide example phrasing
 # ("README claims 8 issuer connectors but only 6 exist"),
 # and any number that quotes the source command immediately
 # adjacent.
@@ -27,7 +26,7 @@
 set -e
 BAD=$(grep -rnE '\b[0-9]+\s+(issuer connectors?|target connectors?|notifier connectors?|discovery connectors?|MCP tools|OpenAPI operations|migrations|database tables|frontend pages|HTTP routes)\b' \
    README.md docs/ 2>/dev/null \
-    | grep -vE 'WORKSPACE-CHANGELOG|seed_demo|demo override' \
+    | grep -vE 'seed_demo|demo override' \
    | grep -vE 'DRIFT HAZARD|Source: |Rebuild|rebuild via|grep -|wc -l|ls -d|find ' \
    | grep -vE 'README claims [0-9]+ issuer connectors but only [0-9]+ exist' \
    || true)