From c2ca148e85c3abd4cb1b3b31c2567be40dbcc591 Mon Sep 17 00:00:00 2001 From: Hiroshi Hatake Date: Tue, 7 Jul 2026 14:49:27 +0900 Subject: [PATCH 1/3] AGENTS: Add notes for Windows exceptions Signed-off-by: Hiroshi Hatake --- AGENTS.md | 14 +++++++++++++- 1 file changed, 13 insertions(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index d064787137d..2d5c36f5ea0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -6,6 +6,10 @@ - Test: `ctest --test-dir build --output-on-failure` - Prefer targeted tests with `ctest --test-dir build -R --output-on-failure` when the affected area is known, because the full enabled suite can be slow. +- On Windows, do not run runtime test cases yet. Runtime tests are not supported + there, so skip them and report the skip instead of treating missing runtime + verification as a failure. Prefer filtered non-runtime CTest runs over the + full suite if the build tree contains runtime tests. - Run a focused integration test with `ctest --test-dir build -R flb-it-opentelemetry --output-on-failure` - Run the in-tree Python integration suite with: @@ -63,6 +67,11 @@ Keep changes scoped: plugin logic in its plugin directory, shared behavior in `s - Add or update tests for behavior changes, especially protocol parsing and encoder/decoder paths. - Prefer targeted tests close to the changed module (`tests/internal`, plugin runtime tests). - Prefer focused `ctest -R ...` runs or specific test binaries when the touched area is known. +- Windows exception: runtime test cases are not supported on Windows yet. When + working on Windows, do not run `tests/runtime`, `flb-rt-*` targets, or runtime + CTest matches as verification. Avoid full-suite CTest runs if they would pick + up runtime tests. Run applicable non-runtime tests instead and state clearly + that runtime verification was skipped because the platform does not support it. - Use `tests/integration` when validating end-to-end plugin behavior, network protocols, downstream request generation, or local fake-server interactions that are awkward to cover in `ctest` binaries alone. @@ -96,6 +105,8 @@ Keep changes scoped: plugin logic in its plugin directory, shared behavior in `s - the exact focused integration command(s) run; - whether valgrind was used; - pass/fail status; + - on Windows, any runtime test cases intentionally skipped because runtime + tests are not supported there; - any concrete blocker if a required run could not be completed. - Keep generated integration artifacts out of git. Do not commit `.venv/`, `.pytest_cache/`, `results/`, or `__pycache__/` under @@ -255,7 +266,8 @@ Keep changes scoped: plugin logic in its plugin directory, shared behavior in `s ### Testing strategy - Use `tests/internal` for core lifecycle/accounting logic. -- Use `tests/runtime` for plugin-level behavior and end-to-end semantics. +- Use `tests/runtime` for plugin-level behavior and end-to-end semantics, except + on Windows where runtime test cases are not supported and must be skipped. - Add regression tests for: - mixed signals - processor drop/modify paths From 39761f8b2a99582d36f0bbc0615522f058f78a57 Mon Sep 17 00:00:00 2001 From: Hiroshi Hatake Date: Tue, 7 Jul 2026 14:53:13 +0900 Subject: [PATCH 2/3] skills: Extract and generalized skills from local MEMORY.md Signed-off-by: Hiroshi Hatake --- AGENTS.md | 21 ++-- skills/README.md | 38 +++++++ skills/fluent-bit/README.md | 29 ++++++ skills/fluent-bit/SKILL.md | 83 ++++++++++++++++ skills/fluent-bit/patch-workflow.md | 87 ++++++++++++++++ skills/fluent-bit/pipeline-architecture.md | 86 ++++++++++++++++ skills/fluent-bit/subsystem-patterns.md | 109 +++++++++++++++++++++ skills/fluent-bit/testing.md | 98 ++++++++++++++++++ 8 files changed, 545 insertions(+), 6 deletions(-) create mode 100644 skills/README.md create mode 100644 skills/fluent-bit/README.md create mode 100644 skills/fluent-bit/SKILL.md create mode 100644 skills/fluent-bit/patch-workflow.md create mode 100644 skills/fluent-bit/pipeline-architecture.md create mode 100644 skills/fluent-bit/subsystem-patterns.md create mode 100644 skills/fluent-bit/testing.md diff --git a/AGENTS.md b/AGENTS.md index 2d5c36f5ea0..45c4178ccdc 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,14 +2,16 @@ ## Preferred Commands - Configure: `cmake -S . -B build -DFLB_TESTS_RUNTIME=On -DFLB_TESTS_INTERNAL=On` +- Configure on Windows: + `cmake -S . -B build -DFLB_TESTS_RUNTIME=Off -DFLB_TESTS_INTERNAL=On` - Build: `cmake --build build -j8` - Test: `ctest --test-dir build --output-on-failure` - Prefer targeted tests with `ctest --test-dir build -R --output-on-failure` when the affected area is known, because the full enabled suite can be slow. - On Windows, do not run runtime test cases yet. Runtime tests are not supported there, so skip them and report the skip instead of treating missing runtime - verification as a failure. Prefer filtered non-runtime CTest runs over the - full suite if the build tree contains runtime tests. + verification as a failure. Configure with `-DFLB_TESTS_RUNTIME=Off` and + prefer filtered non-runtime CTest runs over the full suite. - Run a focused integration test with `ctest --test-dir build -R flb-it-opentelemetry --output-on-failure` - Run the in-tree Python integration suite with: @@ -35,6 +37,8 @@ Keep changes scoped: plugin logic in its plugin directory, shared behavior in `s ## Build, Test, and Development Commands - `cmake -S . -B build -DFLB_TESTS_RUNTIME=On -DFLB_TESTS_INTERNAL=On`: configure with runtime + internal tests. +- `cmake -S . -B build -DFLB_TESTS_RUNTIME=Off -DFLB_TESTS_INTERNAL=On`: + configure on Windows, where runtime tests are unsupported. - `cmake --build build -j8`: compile Fluent Bit and tests. - `ctest --test-dir build --output-on-failure`: run enabled tests. - `ctest --test-dir build -R flb-it-opentelemetry --output-on-failure`: run a focused integration test. @@ -69,9 +73,10 @@ Keep changes scoped: plugin logic in its plugin directory, shared behavior in `s - Prefer focused `ctest -R ...` runs or specific test binaries when the touched area is known. - Windows exception: runtime test cases are not supported on Windows yet. When working on Windows, do not run `tests/runtime`, `flb-rt-*` targets, or runtime - CTest matches as verification. Avoid full-suite CTest runs if they would pick - up runtime tests. Run applicable non-runtime tests instead and state clearly - that runtime verification was skipped because the platform does not support it. + CTest matches as verification. Configure with `-DFLB_TESTS_RUNTIME=Off` so + unsupported runtime targets are not built. Run applicable non-runtime tests + instead and state clearly that runtime verification was skipped because the + platform does not support it. - Use `tests/integration` when validating end-to-end plugin behavior, network protocols, downstream request generation, or local fake-server interactions that are awkward to cover in `ctest` binaries alone. @@ -90,6 +95,9 @@ Keep changes scoped: plugin logic in its plugin directory, shared behavior in `s `cmake --build build -j8` `tests/integration/.venv/bin/python -m pytest -q` `VALGRIND=1 VALGRIND_STRICT=1 tests/integration/.venv/bin/python -m pytest -q` +- On Windows, replace the configure command above with: + `cmake -S . -B build -DFLB_TESTS_RUNTIME=Off -DFLB_TESTS_INTERNAL=On` + and skip runtime test cases because they are not supported there. - Run broader test coverage when changing shared lifecycle, routing, storage, or accounting code. - Validate both success and failure paths (invalid payloads, boundary sizes, null/missing fields). - You can also run specific binaries from `build/bin` (e.g., `./bin/flb-it-opentelemetry`). @@ -178,7 +186,8 @@ Keep changes scoped: plugin logic in its plugin directory, shared behavior in `s path inference before choosing a commit subject. For example, changes only to `AGENTS.md` must use `agents:`, not `docs:`. - For pull-request-style validation, use full history and fetch the base branch - first, matching CI behavior: + first, matching CI behavior. This is required because the checker can fall + back to validating only `HEAD` when the base ref is unavailable: `git fetch --all --prune` `git fetch origin :origin/` - Before pushing a branch or opening/updating a PR, agents must lint the full diff --git a/skills/README.md b/skills/README.md new file mode 100644 index 00000000000..4d0da245c86 --- /dev/null +++ b/skills/README.md @@ -0,0 +1,38 @@ +# LLM Skills + +This directory contains portable Markdown skill bundles for LLM agents working +in this repository. Each skill should live in its own subdirectory with a +`SKILL.md` entrypoint and any focused companion guides it needs. + +## Available Skills + +- Fluent Bit: [`fluent-bit/SKILL.md`](fluent-bit/SKILL.md) + - Repository workflow, testing, patch review, pipeline architecture, and + recurring subsystem guidance for Fluent Bit work. + - Sub-skills: + - [`fluent-bit/patch-workflow.md`](fluent-bit/patch-workflow.md): + implementation, review, and commit workflow. + - [`fluent-bit/pipeline-architecture.md`](fluent-bit/pipeline-architecture.md): + runtime model for shared pipeline changes. + - [`fluent-bit/subsystem-patterns.md`](fluent-bit/subsystem-patterns.md): + recurring subsystem search routes and behavioral checks. + - [`fluent-bit/testing.md`](fluent-bit/testing.md): + focused CTest, integration, valgrind, and Windows runtime-test guidance. + +## How to Use + +Start with the skill entrypoint, then read only the companion files relevant to +the task. For Fluent Bit work, begin with: + +```text +skills/fluent-bit/SKILL.md +``` + +## Adding Skills + +When adding a new skill: + +- create a new subdirectory under `skills/`; +- include a `SKILL.md` entrypoint; +- keep instructions portable and tool-agnostic when possible; +- update this index with the new skill name, entrypoint, and purpose. diff --git a/skills/fluent-bit/README.md b/skills/fluent-bit/README.md new file mode 100644 index 00000000000..e879eeb5174 --- /dev/null +++ b/skills/fluent-bit/README.md @@ -0,0 +1,29 @@ +# Fluent Bit LLM Skills + +This folder contains portable Markdown skills for agents working on the Fluent +Bit repository. They are intentionally tool-agnostic: any LLM can read these +files as instructions, then use whatever shell, editor, or CI interface it has. + +## Files + +- `SKILL.md`: entrypoint and operating principles. +- `testing.md`: focused CTest, integration, and valgrind expectations. +- `patch-workflow.md`: implementation, review, and commit workflow. +- `pipeline-architecture.md`: runtime model for shared pipeline changes. +- `subsystem-patterns.md`: recurring Fluent Bit subsystem routes and checks. + +## Suggested Agent Prompt + +```text +Before working in this repository, read skills/fluent-bit/SKILL.md. +For code changes, also read skills/fluent-bit/patch-workflow.md and +skills/fluent-bit/testing.md. For shared runtime changes, read +skills/fluent-bit/pipeline-architecture.md. For known subsystem areas, read +skills/fluent-bit/subsystem-patterns.md. +``` + +## Maintenance + +Keep these files concise and operational. Add subsystem notes only when they +change how an agent should search, patch, test, or report work in this repo. + diff --git a/skills/fluent-bit/SKILL.md b/skills/fluent-bit/SKILL.md new file mode 100644 index 00000000000..e4efc2bed69 --- /dev/null +++ b/skills/fluent-bit/SKILL.md @@ -0,0 +1,83 @@ +# Fluent Bit Repository Skill + +Use this skill when working in the Fluent Bit repository or in a similar +C/C++ plugin-based telemetry pipeline. It is written for any LLM agent: read the +relevant linked files, inspect the current checkout, make the smallest correct +change, and report exact verification. + +## When to Use + +- A task mentions Fluent Bit source, tests, plugins, runtime behavior, routing, + storage, shutdown, configuration validation, or protocol encoding. +- A task asks whether a reported Fluent Bit bug is still present. +- A task asks for implementation or review of a Fluent Bit patch. +- A task asks for the right focused tests, integration scenarios, or valgrind + checks for a touched Fluent Bit component. + +## Required Reading Order + +1. Read this file. +2. Read `testing.md` before changing behavior or closing out a task. +3. Read `patch-workflow.md` before editing code or reviewing a patch. +4. Read `pipeline-architecture.md` for shared runtime, routing, lifecycle, + processor, chunk, task, storage, metrics, retry, or signal-aware changes. +5. Read `subsystem-patterns.md` when the task touches one of the listed + recurring areas. + +## Operating Principles + +- Verify the current checkout before patching. A report may already be fixed. +- Prefer the repository's existing helpers, source-of-truth resolvers, and + local conventions over new parallel logic. +- Keep changes scoped to the affected component. Put plugin logic in its plugin + directory; shared behavior belongs in `src/`, `include/fluent-bit/`, or `lib/`. +- Fix shared helper semantics when the bug is in a helper, instead of patching + only one visible caller. +- Preserve real input paths. If the request asks to enrich or correct an + existing path, solve it in the relevant layer instead of faking another input + route. +- Treat shutdown, architecture-specific failures, memory errors, and route + accounting mismatches as real lifecycle problems until traced through the + exact failing path. +- Separate validated behavior from environment noise. If a focused test passes + but a broader legacy suite fails for unrelated reasons, report both signals. + +## Standard Commands + +```sh +cmake -S . -B build -DFLB_TESTS_RUNTIME=On -DFLB_TESTS_INTERNAL=On +cmake --build build -j8 +ctest --test-dir build --output-on-failure +ctest --test-dir build -R --output-on-failure +./build/bin/fluent-bit -c conf/fluent-bit.conf +``` + +On Windows, skip runtime test cases. Runtime tests are not supported there yet, +so configure with runtime tests disabled, use applicable non-runtime +verification, and report the runtime-test skip: + +```sh +cmake -S . -B build -DFLB_TESTS_RUNTIME=Off -DFLB_TESTS_INTERNAL=On +cmake --build build -j8 +ctest --test-dir build -R --output-on-failure +``` + +For Python integration scenarios: + +```sh +cd tests/integration && ./setup-venv.sh +cd tests/integration && ./run_tests.py --list +cd tests/integration && ./run_tests.py +``` + +## Close-Out Requirements + +Final responses for implementation tasks should include: + +- What changed, with file paths. +- The exact verification commands run. +- Pass/fail status. +- Whether valgrind was used when integration coverage applies. +- Any runtime tests skipped on Windows because runtime test cases are + unsupported there. +- Any concrete blocker for required tests that could not run. diff --git a/skills/fluent-bit/patch-workflow.md b/skills/fluent-bit/patch-workflow.md new file mode 100644 index 00000000000..29ea7dcea8f --- /dev/null +++ b/skills/fluent-bit/patch-workflow.md @@ -0,0 +1,87 @@ +# Fluent Bit Patch and Review Workflow + +Use this guide when implementing or reviewing Fluent Bit changes. + +## Before Editing + +- Inspect the current checkout. Do not assume a reported bug is still live. +- Search with `rg` first. +- Read the exact source path, tests, and helpers involved. +- Trace from public configuration or input surface to the failing behavior. +- Identify whether the problem belongs in a plugin, a shared helper, core + runtime, a bundled library, or tests. + +## Implementation Rules + +- Keep patches minimal and scoped. +- Use existing helpers and source-of-truth functions before adding new logic. +- When a shared helper has wrong semantics, fix the helper and update callers + consistently. +- Preserve explicit zero values; use clear sentinels for unknown values. +- Do not downgrade real I/O, parse, or lifecycle failures just to quiet logs. +- Do not add broad refactors or formatting churn around the fix. +- Follow Fluent Bit C style: + - variables at function start; + - braces for all `if`, `else`, `while`, and `do` blocks; + - function opening brace on the next line; + - `snake_case` names with existing component prefixes; + - `/* ... */` comments only where useful. + +## Review Stance + +Prioritize: + +- bugs and behavioral regressions; +- missing tests; +- lifecycle or memory-safety risks; +- config compatibility risks; +- route, signal, storage, or retry accounting regressions. + +When reviewing claims like "this enables validation" or "this caches +resolution," distinguish: + +- what the current patch actually wires; +- what runtime or binding plumbing is still missing; +- whether behavior is one-shot lookup, repeated resolver use, or true cache + semantics. + +## Commit Guidance + +Use component-prefix subjects consistent with local history: + +```sh +git commit -s -m "component: short imperative description" +``` + +Common examples: + +- `engine: fix flush buffer handling` +- `tests: internal: add parser regression coverage` +- `tests: integration: cover schema registry resolution` + +Do not invent generic prefixes when the repository linter infers a narrower +prefix. Run the linter when creating commits: + +```sh +python .github/scripts/commit_prefix_check.py +``` + +If `gitpython` is missing: + +```sh +python3 -m pip install gitpython +``` + +Before pushing or opening a PR, fetch the base branch and lint the PR range, not +just `HEAD`. The checker can fall back to `HEAD`-only validation if the base ref +is missing locally: + +```sh +git fetch --all --prune +git fetch origin :origin/ +GITHUB_EVENT_NAME=pull_request GITHUB_BASE_REF= \ + python .github/scripts/commit_prefix_check.py +``` + +Do not open issues, pull requests, or remote branches unless explicitly asked. +Do not rewrite history, amend commits, or force-push unless explicitly asked. diff --git a/skills/fluent-bit/pipeline-architecture.md b/skills/fluent-bit/pipeline-architecture.md new file mode 100644 index 00000000000..600b7118b0f --- /dev/null +++ b/skills/fluent-bit/pipeline-architecture.md @@ -0,0 +1,86 @@ +# Fluent Bit Pipeline Architecture Skill + +Use this guide for shared runtime, routing, task, chunk, storage, processor, +filter, output, metric, retry, and shutdown changes. + +## Runtime Model + +Data moves through: + +```text +input -> chunk -> router -> task -> filter/processor -> output -> engine result +``` + +Routing is per output instance. One chunk can fan out to many routes. Route +state is independent, so success, retry, and drop can differ for each output. + +## Data Units + +- A signal is the high-level type: logs, metrics, traces, profiles, or blobs. +- A record/event is the logical payload unit inside a signal. +- A chunk is the persisted or queued container, often MessagePack-backed. +- A task is the engine execution unit for a chunk across routes. + +Never assume "one chunk equals one route" or "one serialized event equals one +log record" in shared code. + +## Component Responsibilities + +- Inputs (`plugins/in_*`) create or append data and trigger ingestion. +- Input chunk layer (`src/flb_input_chunk.c`) manages chunk lifecycle, routing + masks, storage pressure, and drop/release behavior. +- Router (`src/flb_router*.c`) resolves tag and signal matches to outputs. +- Task layer (`src/flb_task.c`) tracks per-route state and retries. +- Filters (`plugins/filter_*`) run on matching streams before output flush. +- Processors (`plugins/processor_*`) can run in input or output contexts and may + mutate or drop payloads. +- Outputs (`plugins/out_*`) serialize or protocol-encode and return flush + results. +- Engine (`src/flb_engine.c`) applies retry/drop accounting and task teardown. + +## Signal-Aware Rules + +- Shared paths must branch correctly by event type. +- Log-only record semantics may not apply to metrics, traces, profiles, or + blobs. +- Group or metadata markers can be serialized events; treat them as data-shape + artifacts unless an interface explicitly requires them. + +## Counting and Metrics + +Separate: + +- serialized events in a buffer; +- logical records after processing; +- per-route processed, retry, and drop counters; +- byte accounting for chunk bytes versus route-effective bytes. + +Prefer route-aware values for route metrics. Preserve explicit zero values. + +## Retry and Drop Semantics + +- `FLB_OK`: route succeeded. +- `FLB_RETRY`: route keeps the task or chunk for retry scheduling. +- `FLB_ERROR`: route failure/drop path. + +Final chunk release happens only when all active routes are resolved. + +## Storage and Backlog + +In-memory and filesystem backlog paths may use different code paths. Validate +both when touching chunk, task, storage, lifecycle, or accounting code. +Backlog-loaded chunks must preserve route state and accounting parity with +live-ingested chunks. + +## Review Checklist + +- Trace one full path for affected signals: + input -> chunk -> task -> output -> engine completion. +- Verify fan-out behavior: one chunk, multiple outputs. +- Verify processor behavior: drop, modify, and no-op in input and output + contexts when relevant. +- Verify empty payload behavior. +- Verify metrics and counters for success, retry, and drop paths. +- Verify shutdown cleanup if event channels, file descriptors, coroutines, or + scheduler state are touched. + diff --git a/skills/fluent-bit/subsystem-patterns.md b/skills/fluent-bit/subsystem-patterns.md new file mode 100644 index 00000000000..b5bb2fbe9ef --- /dev/null +++ b/skills/fluent-bit/subsystem-patterns.md @@ -0,0 +1,109 @@ +# Fluent Bit Subsystem Patterns + +Use this guide as a routing map for recurring Fluent Bit tasks. Revalidate exact +code in the current checkout before relying on any pattern. + +## Config Map and Proxy Plugins + +Search first: + +```sh +rg -n "flb_config_map_create|flb_config_map_properties_check|flb_plugin_proxy|config_map" \ + src include plugins +``` + +Key rule: C-side `config_map` field wiring can participate in unknown-key +validation, but it may not be end-to-end for language bindings. Check whether +the binding surface can pass a real config map and whether custom plugin +registration plumbing uses it. + +## Node Exporter Metrics File Logging + +Search first: + +```sh +rg -n "ne_utils|thermal|throttle|ENOENT|FLB_LOG_ERROR|FLB_LOG_DEBUG" \ + plugins/in_node_exporter_metrics +``` + +Key rule: missing optional sysfs files can be debug-only, but real `open()` or +`read()` failures should remain errors. A durable patch shape is centralized +errno-aware helper logic, with only `ENOENT` eligible for downgrade. + +## Rewrite Tag and Emitter Backlog + +Search first: + +```sh +rg -n "pending_bytes|mem_buf_limit|is_queue_overlimit|in_emitter|rewrite_tag" \ + plugins tests +``` + +Key rule: verify whether the current branch already has bounded backlog and +overlimit handling before patching. If already fixed, rerun focused coverage and +stop without editing code. + +## Kubernetes Filter on Fluent Bit Internal Logs + +Search first: + +```sh +rg -n "Kube_Namespace_File|kube_local_fluentbit_logs|fluentbit_logs|flb_kube_meta_get_local" \ + plugins tests +``` + +Key rule: keep internal logs as real `in_fluentbit_logs` input. Add metadata in +the Kubernetes filter path instead of pretending the records came from tail or a +different tag source. + +## Scheduler and Shutdown Regressions + +Search first: + +```sh +rg -n "flb_sched_destroy|mk_event_channel_destroy|processor_private_inputs_use_main_loop" \ + src include tests +rg -n "ch_events" src include tests +``` + +Key rule: shutdown crashes often require tracing the exact event-channel, +file-descriptor, scheduler, and processor path. Architecture-specific failures +can expose real initialization or teardown bugs. + +## in_ebpf OpenSSL Path Discovery + +Search first: + +```sh +rg -n "trace_openssl|FLB_IN_EBPF_LIBSSL_PATH|OPENSSL_SSL_LIBRARY|OpenSSL::SSL|bpf.c.in" \ + plugins/in_ebpf +``` + +Key rule: the `libssl` path is baked into generated BPF source at build time. +Fix path discovery in CMake/template generation rather than hardcoding +`libssl.so.3` in source. + +## Kafka Avro and Schema Registry + +Search first: + +```sh +rg -n "schema_registry|flb_kafka_schema_registry_resolve|FLB_HAVE_AVRO_ENCODER|Confluent" \ + plugins/out_kafka tests/integration tests/internal +``` + +Key rule: parser-only internal coverage is not enough for live resolver +behavior. Use `tests/integration/scenarios/out_kafka` for mock schema-registry +coverage and distinguish remote resolution from true local-cache semantics. + +## Avro Encoder Range Errors + +Search first: + +```sh +rg -n "msgpack2avro|FLB_AVRO_RANGE_ERROR|range|avro" src tests/internal +``` + +Key rule: nested map conversion must preserve earlier range failures. Add +focused internal regression coverage, including cases where the bad field is not +the final field. diff --git a/skills/fluent-bit/testing.md b/skills/fluent-bit/testing.md new file mode 100644 index 00000000000..a010fde67f9 --- /dev/null +++ b/skills/fluent-bit/testing.md @@ -0,0 +1,98 @@ +# Fluent Bit Testing Skill + +Use this guide to choose and report verification for Fluent Bit changes. + +## Test Selection + +- Prefer targeted tests when the affected area is known: + +```sh +ctest --test-dir build -R --output-on-failure +``` + +- Use `tests/internal` for core lifecycle, accounting, parser, encoder, and + helper logic. +- Use `tests/runtime` for plugin-level behavior and end-to-end C test binaries. +- Use `tests/integration` for network protocols, downstream request generation, + fake-server behavior, and plugin behavior that is awkward to cover in CTest. +- Run broader tests when changing shared lifecycle, routing, storage, task, + scheduler, or accounting behavior. + +## Windows Runtime Test Exception + +Runtime test cases are not supported on Windows yet. On Windows, do not run +`tests/runtime`, `flb-rt-*` targets, or CTest filters that select runtime test +cases as verification. Run applicable non-runtime tests instead, such as focused +internal tests or build-only checks, and report the skip explicitly. Configure +with runtime tests disabled so unsupported runtime targets are not built: + +```sh +cmake -S . -B build -DFLB_TESTS_RUNTIME=Off -DFLB_TESTS_INTERNAL=On +cmake --build build -j8 +ctest --test-dir build -R --output-on-failure +``` + +## Integration Test Expectations + +If a touched component has a focused `tests/integration` scenario, run it before +closing the task. Run it once normally and once with valgrind when possible. + +Default verification shape for non-Windows platforms: + +```sh +./tests/integration/setup-venv.sh +cmake -S . -B build -DFLB_TESTS_RUNTIME=On -DFLB_TESTS_INTERNAL=On +cmake --build build -j8 +tests/integration/.venv/bin/python -m pytest -q +VALGRIND=1 VALGRIND_STRICT=1 \ + tests/integration/.venv/bin/python -m pytest -q +``` + +On Windows, replace the configure command with the +`-DFLB_TESTS_RUNTIME=Off` variant above and do not run runtime test cases. + +Equivalent run-test wrapper shape: + +```sh +cd tests/integration +./run_tests.py +./run_tests.py --valgrind --valgrind-strict +``` + +## Reporting Blockers + +Do not silently skip required integration or valgrind coverage. Report the exact +blocker, such as: + +- missing `build/bin/fluent-bit`; +- missing Python virtualenv; +- missing `pytest` or another Python dependency; +- unavailable scenario; +- missing `valgrind`; +- network restriction during dependency setup; +- Windows runtime test skip because runtime tests are not supported there; +- infrastructure failure unrelated to the patch. + +## Useful Validation Habits + +- Rerun CMake before building a brand-new test target in an older build tree. + Target-not-found failures are often stale build trees, not source failures. +- Use `git diff --check` after edits to catch whitespace problems. +- Validate success and failure paths: invalid payloads, boundary sizes, + null/missing fields, and non-last bad fields when parsing maps. +- Keep generated integration artifacts out of git: + `.venv/`, `.pytest_cache/`, `results/`, and `__pycache__/`. +- If broad tests fail after focused tests pass, inspect whether failures are + pre-existing or unrelated before expanding the patch. + +## Close-Out Proof Format + +Include exact commands and outcomes: + +```text +Verification: +- PASS: cmake --build build -j8 --target +- PASS: ctest --test-dir build -R '' --output-on-failure +- SKIPPED: runtime tests on Windows because runtime test cases are unsupported +- BLOCKED: VALGRIND=1 ... failed because valgrind is not installed +``` From 11625e0817af89447ae1c47a430f4acd1933f008 Mon Sep 17 00:00:00 2001 From: Hiroshi Hatake Date: Tue, 7 Jul 2026 15:09:56 +0900 Subject: [PATCH 3/3] skills: Add guardrails to prevent editing bundled libraries Signed-off-by: Hiroshi Hatake --- AGENTS.md | 14 ++++++++++++++ skills/fluent-bit/SKILL.md | 6 ++++++ skills/fluent-bit/patch-workflow.md | 10 ++++++++++ 3 files changed, 30 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 45c4178ccdc..1f51512df2d 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -35,6 +35,19 @@ Fluent Bit is a C/C++ monorepo built with CMake. Keep changes scoped: plugin logic in its plugin directory, shared behavior in `src/` or `lib/`. +## Bundled Library Changes +- Treat `lib/` as bundled third-party or separately maintained code unless the + specific path is clearly Fluent Bit-owned. +- Before editing bundled library code, ask for explicit user confirmation. If + the agent environment supports confirmation popups, use one; otherwise ask in + chat before writing files. +- Prefer changes that can be sent upstream as a focused patch. Keep bundled + library patches isolated from Fluent Bit glue code, and document the upstream + project/path in the close-out. +- Do not mix bundled library edits with unrelated Fluent Bit core, plugin, + documentation, or test changes in the same commit unless the user explicitly + asks for that structure. + ## Build, Test, and Development Commands - `cmake -S . -B build -DFLB_TESTS_RUNTIME=On -DFLB_TESTS_INTERNAL=On`: configure with runtime + internal tests. - `cmake -S . -B build -DFLB_TESTS_RUNTIME=Off -DFLB_TESTS_INTERNAL=On`: @@ -205,6 +218,7 @@ Keep changes scoped: plugin logic in its plugin directory, shared behavior in `s - Do not open issues, pull requests, or remote branches unless the user explicitly asks. - Do not rewrite git history, amend commits, or force-push unless the user explicitly asks. - Do not revert user changes outside the requested scope. +- Do not edit bundled libraries under `lib/` without explicit confirmation. - Prefer minimal patches that avoid unrelated formatting or refactoring churn. ## Agent Playbook (Pipeline Architecture Primer) diff --git a/skills/fluent-bit/SKILL.md b/skills/fluent-bit/SKILL.md index e4efc2bed69..b8594be66dd 100644 --- a/skills/fluent-bit/SKILL.md +++ b/skills/fluent-bit/SKILL.md @@ -31,6 +31,10 @@ change, and report exact verification. local conventions over new parallel logic. - Keep changes scoped to the affected component. Put plugin logic in its plugin directory; shared behavior belongs in `src/`, `include/fluent-bit/`, or `lib/`. +- Treat bundled libraries under `lib/` as third-party or separately maintained + code unless the path is clearly Fluent Bit-owned. Ask for explicit user + confirmation before editing them, using a confirmation popup when available. + Keep those edits isolated and upstreamable as focused patches. - Fix shared helper semantics when the bug is in a helper, instead of patching only one visible caller. - Preserve real input paths. If the request asks to enrich or correct an @@ -80,4 +84,6 @@ Final responses for implementation tasks should include: - Whether valgrind was used when integration coverage applies. - Any runtime tests skipped on Windows because runtime test cases are unsupported there. +- Any bundled library patch touched, including the upstream project/path and + confirmation that the user approved editing it. - Any concrete blocker for required tests that could not run. diff --git a/skills/fluent-bit/patch-workflow.md b/skills/fluent-bit/patch-workflow.md index 29ea7dcea8f..b2d6fad336d 100644 --- a/skills/fluent-bit/patch-workflow.md +++ b/skills/fluent-bit/patch-workflow.md @@ -10,6 +10,9 @@ Use this guide when implementing or reviewing Fluent Bit changes. - Trace from public configuration or input surface to the failing behavior. - Identify whether the problem belongs in a plugin, a shared helper, core runtime, a bundled library, or tests. +- If the fix would touch bundled library code under `lib/`, get explicit user + confirmation before editing. Use a confirmation popup when the environment + supports one; otherwise ask in chat. ## Implementation Rules @@ -20,6 +23,8 @@ Use this guide when implementing or reviewing Fluent Bit changes. - Preserve explicit zero values; use clear sentinels for unknown values. - Do not downgrade real I/O, parse, or lifecycle failures just to quiet logs. - Do not add broad refactors or formatting churn around the fix. +- Keep bundled library edits isolated from Fluent Bit glue changes and write + them as upstreamable patches for the library's own project. - Follow Fluent Bit C style: - variables at function start; - braces for all `if`, `else`, `while`, and `do` blocks; @@ -59,6 +64,11 @@ Common examples: - `tests: internal: add parser regression coverage` - `tests: integration: cover schema registry resolution` +For bundled library changes, keep the library patch in its own commit unless the +user explicitly asks otherwise. Use the prefix accepted for that path by the +repository linter, and mention the upstream project/path in the commit body when +that context is useful. + Do not invent generic prefixes when the repository linter infers a narrower prefix. Run the linter when creating commits: