docs(vision): Zero Noise — the doctrine #5523
1 changed file+118−0
Addeddocs/VISION-ZERO-NOISE.md+118−0View fileUnifiedSplit
@@ -0,0 +1,118 @@
1# Zero Noise — the doctrine (2026-08-24)
2
3The most intelligent system is not the one with the most features or the
4biggest models. It is the one that **never wastes a developer's
5attention**. That is the whole vision, and every section below is a
6buildable consequence of it.
7
8The industry context this answers (researched 2026-08-23): organizations
9average 500k+ security alerts at 95–98% junk; SAST false-positive rates
10exceed 68%; 15–30% of AI review comments are low-value; the market leader
11injected ads into 1.5M pull requests and had 112 hours of downtime in a
12year. The entire tooling industry is training developers to ignore their
13tools. Gluecron's product is the opposite reflex: **when this platform
14speaks, it is worth listening.**
15
16## The one promise
17
18> Every signal we show you is true, and every true thing gets shown.
19
20Both halves bind. A false positive breaks the first half; a silent
21failure (mirror dead for weeks, PR page frozen, "All systems operational"
22unconditionally) breaks the second. The platform's history shows both
23failure classes — and the machinery that has been eliminating them is the
24most defensible thing we own.
25
26## Pillar 1 — Runs without AI (the sovereignty invariant)
27
28**If Anthropic goes down, Gluecron does not.** Owner's words, 2026-08-24.
29
30- The ship path — push → CI → gates → merge → deploy → monitor → page —
31 is deterministic end to end. This is already enforced by the invariant
32 suite (scorecard row 19; manual-first pass 2026-08-19) and must stay a
33 tested property, not a remembered one.
34- AI is an amplifier on top: review depth, triage, repair, chat. Every AI
35 surface has an off switch and an honest disabled state. When the AI
36 provider is unreachable, surfaces say so and offer the manual path —
37 never a spinner, never a fake result, never a blocked merge.
38- Corollary for this doctrine itself: the noise machinery below must not
39 depend on AI to function. Deterministic gates (env-drift, error-contract,
40 secret scan, exclusion-rot, copy-honesty) are the backbone — in the week
41 of 2026-08-18 they caught the platform's own agents five times with zero
42 false positives, no model involved. AI-powered signals are held to the
43 same published standard, and are the first thing to shed under
44 degradation.
45
46## Pillar 2 — Verified before shown
47
48No probabilistic finding reaches a human until an independent pass tried
49to kill it. The review pipeline becomes finder → skeptic → only survivors
50post. The industry filters noise after showing it; we filter before.
51Deterministic findings (a failing test, a missing env var) skip the
52skeptic — determinism is its own verification.
53
54## Pillar 3 — Coverage is derived, never curated
55
56Adopted from the Vapron spine doctrine (2026-08-23): if adding a feature
57requires remembering to add its monitoring, the monitoring layer is
58broken. Routes auto-become probed surfaces (the route registry exists);
59docs claims auto-verify against artifacts; systemd units diff against
60their written sources; exclusion lists rot-check themselves
61(exclusion-rot.test.ts). New code is born observed.
62
63## Pillar 4 — Published precision
64
65We publish our false-positive rate on /status, next to uptime, computed
66not claimed:
67
68- Every AI review comment carries a resolvable verdict — acted-on,
69 dismissed-as-wrong, or expired-unjudged — set by one click from the PR
70 author or a reviewer.
71- Precision = acted-on / (acted-on + dismissed-as-wrong) over a rolling
72 30 days, shown with the sample size. Below a floor sample, the surface
73 says "not enough verdicts yet" — never a fabricated number.
74- A falling precision rate is treated as an incident, exactly like
75 downtime: it pages, it gets a postmortem, it blocks "more AI" features
76 until recovered.
77
78Nobody in developer tooling publishes this number. Publishing it is both
79an unanswerable claim and a whip at our own backs — the same move as the
80/guarantees page with tests behind it.
81
82## Pillar 5 — Trust in people, not just signals
83
84Identity and provenance are noise problems too: an unverified
85"contributor" claim and a fork stripped of lineage are false positives
86about *people*. Verified-identity badges, fork provenance, signed-commit
87verification, and the PR ledger that cannot drift (merge auto-detection,
882026-08-22) all live under this doctrine.
89
90## What this forbids
91
92- Any surface that advertises liveness it cannot prove (the
93 "emptiness on display" class — banned by copy-honesty tests).
94- Any alert without a consumer who can act on it, and any alert channel
95 that fires >1/hour for a persisting condition (rate-limit, don't spam).
96- Any exclusion, suppression, or skip list without a rot check.
97- Any AI feature without: an off switch, an honest degraded state, and a
98 verdict path that feeds the published precision number.
99- Any "recovered" status that was not re-verified (a restart exiting 0
100 proves nothing — Vapron medic contract).
101
102## Build map (in order)
103
1041. **Signal verdicts + published precision** — migration + one-click
105 verdict UI on AI review comments + /status "Signal precision" section
106 with honest empty state. (In build, 2026-08-24.)
1072. **Verified-before-shown** — the skeptic pass in the review pipeline.
1083. **Actions compatibility** — the top GitHub Actions run unmodified
109 (`uses:` shim); the real lock-in is workflows, not git. Pairs with the
110 /api/v3 compat shim (2026-08-22).
1114. **Derived-coverage sweep** — route registry → probe autogen, docs
112 claim-truth checker (hourly), unit drift check.
1135. **Precision-as-incident wiring** — the falling-rate page.
114
115The cohort this wins: teams of 1–50 leaving GitHub over reliability,
116forced AI, ads in PRs, and pricing — documented, growing, and currently
117landing on hosts that take their code but not their workflows. They are
118not looking for a bigger GitHub. They are looking for relief.
0119
c comment · e edit title · m merge · a approve · r request changes · ? shortcuts