mirror of
https://github.com/shankar0123/certctl.git
synced 2026-06-07 20:31:30 +00:00
docs(README,features,examples): replace stale source counts with rebuild commands (S-1 master)
Closes two 2026-04-24 audit findings — one P1 (cat-s1-9ce1cbe26876,
README + features.md cite stale numeric counts) and one P2
(cat-s1-features_md_issuer_count_contradiction, features.md self-
disagreed on issuer count saying 9 in two places + 12 in two others).
Both root in a CLAUDE.md invariant: "Numeric claims about current
state rot the instant the next release lands... Before adding any
current-state count, delete it and write the command instead."
Per-site changes:
- docs/features.md::"At a Glance" table — replaced 12 hardcoded counts
with `rebuild via <command>` references quoting the canonical
source-of-truth grep from CLAUDE.md::"Current-state commands".
- docs/features.md::Issuer Connectors section — dropped "9 issuer
connectors" (stale; live: 12) and "12 IssuerType constants" prose;
prose now references the rebuild command.
- docs/features.md::Target Connectors section — same treatment for
"14 target connector types".
- docs/features.md::"Per-type config schema validation for all 9
issuer types" — same treatment.
- docs/features.md::"80 MCP tools covering all API endpoints" — same.
- docs/features.md::Web Dashboard section — dropped "24 pages wired"
+ the "(25 Route elements, 24 pages)" comment.
- docs/examples.md::"Beyond These Examples" — dropped "7 issuer
backends and 10 target connectors" prose; references features.md
and the rebuild commands.
CI regression guardrail:
- .github/workflows/ci.yml::"Forbidden hardcoded source-count prose
regression guard (S-1)" — grep-fails the build if any of the
blocked phrases (e.g. "9 issuer connectors", "21 database tables",
"80 MCP tools") reappears in README or docs/. Allowlists demo-
fixture prose ("32 certificates" — seed_demo.sql facts), historical
WORKSPACE-CHANGELOG counts, the testing-guide example phrasing,
and any number adjacent to a quoted rebuild command.
Verification:
- S-1 guardrail dry-run on post-fix tree → empty (good)
- golangci-lint v2.11.4 run ./... → 0 issues
- tsc --noEmit → clean
- vitest, vite build unchanged from pre-S-1 baseline (no JS/TS touched)
Audit findings closed:
- cat-s1-9ce1cbe26876 (P1, README + features.md stale numeric counts)
- cat-s1-features_md_issuer_count_contradiction (P2, features.md
self-contradiction on issuer count)
Deferred follow-ups:
- WORKSPACE-CHANGELOG.md historical-milestone counts intentionally
preserved (those are point-in-time facts about shipped slices, not
current-state claims). README demo-fixture counts ("32 certs, 10
issuers") preserved — those describe the seed_demo.sql shape, not
the live source surface.
This commit is contained in:
@@ -611,6 +611,51 @@ jobs:
|
||||
working-directory: web
|
||||
run: npx vite build
|
||||
|
||||
- name: Forbidden hardcoded source-count prose regression guard (S-1)
|
||||
# S-1 master closed cat-s1-9ce1cbe26876 (README + features.md
|
||||
# stale numeric counts; explicit CLAUDE.md violation per
|
||||
# "version-stamped numbers rot") and
|
||||
# cat-s1-features_md_issuer_count_contradiction (features.md
|
||||
# self-disagreed on issuer count: 9 vs 12 in the same doc).
|
||||
# The fix replaced source-derived numbers in prose with
|
||||
# "rebuild via <command>" patterns documented in CLAUDE.md::
|
||||
# "Current-state commands". This step grep-fails the build if
|
||||
# any of the previously-stale sites reintroduces a hardcoded
|
||||
# count.
|
||||
#
|
||||
# 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
|
||||
# ("README claims 8 issuer connectors but only 6 exist"),
|
||||
# and any number that quotes the source command immediately
|
||||
# adjacent.
|
||||
#
|
||||
# See coverage-gap-audit-2026-04-24-v5/unified-audit.md
|
||||
# cat-s1-9ce1cbe26876 + cat-s1-features_md_issuer_count_contradiction
|
||||
# for closure rationale.
|
||||
run: |
|
||||
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 '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)
|
||||
if [ -n "$BAD" ]; then
|
||||
echo "S-1 regression: hardcoded source-count prose reappeared:"
|
||||
echo "$BAD"
|
||||
echo ""
|
||||
echo "CLAUDE.md rule: 'Numeric claims about current state rot.'"
|
||||
echo "Replace the count with the grep command from CLAUDE.md::"
|
||||
echo "'Current-state commands' (e.g. 'ls -d internal/connector/issuer/*/ | wc -l')"
|
||||
echo "or rephrase to reference the rebuild command on the same line."
|
||||
echo "See coverage-gap-audit-2026-04-24-v5/unified-audit.md"
|
||||
echo "cat-s1-9ce1cbe26876 for closure rationale."
|
||||
exit 1
|
||||
fi
|
||||
echo "S-1 stale-counts guardrail: clean."
|
||||
|
||||
helm-lint:
|
||||
name: Helm Chart Validation
|
||||
runs-on: ubuntu-latest
|
||||
|
||||
Reference in New Issue
Block a user