From 6ead96ff8e2f5d6edf6eaa8d54af65e4f7f9accb Mon Sep 17 00:00:00 2001 From: Konstantins Feofantovs Date: Sat, 29 Aug 2026 09:59:35 +0300 Subject: [PATCH] docs: development.md describes how the agent is built, not how it is sold The stability check was product validation in a testing document: a week-long comparison of two spool captures on a long-lived cluster, to decide whether a finding is stable enough to show. `docs/` ships with the Apache-2.0 repository, and its reader is looking for how the software is built and tested. `backend-requirements.md` justified the configuration fingerprint by naming that procedure; the obligation stands, its wording is now self-contained. Co-Authored-By: Claude Opus 5 (1M context) Claude-Session: https://claude.ai/code/session_011YRKuL97KRndaopfpixrhp --- docs/backend-requirements.md | 4 ++-- docs/development.md | 22 ---------------------- 2 files changed, 2 insertions(+), 24 deletions(-) diff --git a/docs/backend-requirements.md b/docs/backend-requirements.md index 2a027c0..2cd23e2 100644 --- a/docs/backend-requirements.md +++ b/docs/backend-requirements.md @@ -99,8 +99,8 @@ The agent ships, per cluster: transmitted; the backend MUST NOT expect or request them - a fingerprint (hash + last-change timestamp) of the effective filter configuration, carrying no configuration content. Every upload is - attributable to the configuration that produced it, so stability checks - can distinguish "the data changed" from "the filters changed" + attributable to the configuration that produced it, so "the data changed" + can be told from "the filters changed" - agent self-info: version, install profile, and effective RBAC summary, so every report can state what its findings do and do not rest on. The active usage signal set (which kubelet signals โ€” e.g. PSI โ€” this cluster exposes) diff --git a/docs/development.md b/docs/development.md index b9fe879..e0e7e18 100644 --- a/docs/development.md +++ b/docs/development.md @@ -96,28 +96,6 @@ A PR is mergeable when: is the whole reason the raw manifests were deleted rather than kept as a reference. The kind node-image matrix pins the oldest supported Kubernetes minor (see the README support policy) and a current release. -- **The stability check takes a week and cannot be a CI gate.** kind proves the - mechanism on a cluster we populated ourselves. It cannot show whether a week of - ordinary cluster life moves the agent's facts more than the cluster itself - moved. That is checked on a long-lived cluster: capture the spool twice, seven - days apart, and compare per workload โ€” the resource envelope, the build, the - node and zone attribution, the usage windows. Every difference must be - explainable by something that happened in the cluster. - - Two conditions make the comparison valid, and both follow from decisions made - elsewhere. The agent runs uninterrupted across the interval: restart counters - are baselined at startup ([ADR 0020](adr/0020-container-restart-journal.md) - ยง5), so a restart moves their origin. And the payloads are copied out at the - first capture, because the spool sweeps unacknowledged files after - `DefaultMaxAge` and is a queue, not an archive. - - A record that disappears is not automatically a defect. The Go inventory lives - only while its workload does - ([ADR 0018](adr/0018-inventory-records-live-only-while-their-workload-does.md)), - and revisions are bounded by the Deployment's own history - ([ADR 0030](adr/0030-deployment-revisions.md)). Each capture's coverage report - is read beside its payloads, so a shift in what was collected is not mistaken - for a shift in what is true. - Unit tests live next to the code (`*_test.go`); e2e lives under `test/`. ## CI gates