docs(git): add branch policy and workflow rules

guides/git-workflow.md

@@ -53,11 +53,12 @@ Examples:
 
 ## Agent Rule
 
-When starting any non-trivial task (feature, bug fix, improvement), an AI agent must:
+When starting any task (feature, bug fix, improvement, documentation), an AI agent must:
 
-1. Verify `main` is current with `origin/main`.
-2. Create a feature branch with an appropriate prefix.
-3. Do all work on that branch.
-4. Push the branch and instruct the user to open a PR instead of merging directly.
+1. Do not edit or commit while on `main`. If currently on `main`, create a branch before editing files.
+2. Verify `main` is current with `origin/main`.
+3. Create a feature branch with an appropriate prefix.
+4. Do all work on that branch.
+5. Push the branch and instruct the user to open a PR instead of merging directly.
 
-Trivial one-line fixes or documentation typos may be committed to `main` only when explicitly requested by the user.
+No direct commits to `main`, including trivial documentation fixes, unless the repository owner explicitly overrides this rule for that exact change.

include/logit_cpp/logit/loggers/OtlpHttpLogger.hpp

@@ -344,12 +344,18 @@ namespace logit {
 
                 if (m_config.compression == OtlpCompression::Gzip) {
                     if (!compress_string_gzip(chunk, post_content, m_config.compression_level)) {
+                        // Compression failed: fallback to uncompressed payload.
+                        // Count this as a failed export attempt so operators can observe compression issues.
+                        m_state->failed_exports.fetch_add(1);
                         post_content = std::move(chunk);
                     } else {
                         chunk_headers.emplace("Content-Encoding", "gzip");
                     }
                 } else if (m_config.compression == OtlpCompression::Zstd) {
                     if (!compress_string_zstd(chunk, post_content, m_config.compression_level)) {
+                        // Compression failed: fallback to uncompressed payload.
+                        // Count this as a failed export attempt so operators can observe compression issues.
+                        m_state->failed_exports.fetch_add(1);
                         post_content = std::move(chunk);
                     } else {
                         chunk_headers.emplace("Content-Encoding", "zstd");

include/logit_cpp/logit/loggers/otlp/OtlpCompression.hpp

@@ -17,6 +17,12 @@ namespace logit {
 
 enum class OtlpCompression { None, Gzip, Zstd };
 
+/// \brief Compress a string with gzip.
+/// \param input Uncompressed data.
+/// \param[out] output Compressed result (valid only on success).
+/// \param level Compression level 1-9.
+/// \return true on success, false if zlib is unavailable or compression fails.
+/// \note Callers must check the return value and handle fallback explicitly.
 inline bool compress_string_gzip(const std::string& input, std::string& output, int level) {
 #if defined(LOGIT_HAS_ZLIB)
     z_stream zs;
@@ -65,6 +71,12 @@ inline bool compress_string_gzip(const std::string& input, std::string& output,
 #endif
 }
 
+/// \brief Compress a string with zstd.
+/// \param input Uncompressed data.
+/// \param[out] output Compressed result (valid only on success).
+/// \param level Compression level 1-19.
+/// \return true on success, false if zstd is unavailable or compression fails.
+/// \note Callers must check the return value and handle fallback explicitly.
 inline bool compress_string_zstd(const std::string& input, std::string& output, int level) {
 #if defined(LOGIT_HAS_ZSTD)
     if (level < 1) level = 1;