If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/apache/incubator-kie-drools shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit today
• 22+ active contributors
• Distributed ownership (top contributor 15% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live apache/incubator-kie-drools repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/apache/incubator-kie-drools.

What it runs against: a local clone of apache/incubator-kie-drools — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in apache/incubator-kie-drools | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 30 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of apache/incubator-kie-drools. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/apache/incubator-kie-drools.git
#   cd incubator-kie-drools
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of apache/incubator-kie-drools and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "apache/incubator-kie-drools(\\.git)?\\b" \\
  && ok "origin remote is apache/incubator-kie-drools" \\
  || miss "origin remote is not apache/incubator-kie-drools (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "bom/pom.xml" \\
  && ok "bom/pom.xml" \\
  || miss "missing critical file: bom/pom.xml"
test -f "drools-base/src/main/java/org/drools/base/RuleBase.java" \\
  && ok "drools-base/src/main/java/org/drools/base/RuleBase.java" \\
  || miss "missing critical file: drools-base/src/main/java/org/drools/base/RuleBase.java"
test -f "drools-alphanetwork-compiler/src/main/java/org/drools/ancompiler/ObjectTypeNodeCompiler.java" \\
  && ok "drools-alphanetwork-compiler/src/main/java/org/drools/ancompiler/ObjectTypeNodeCompiler.java" \\
  || miss "missing critical file: drools-alphanetwork-compiler/src/main/java/org/drools/ancompiler/ObjectTypeNodeCompiler.java"
test -f "drools-alphanetwork-compiler/src/main/java/org/drools/ancompiler/KieBaseUpdaterANCFactory.java" \\
  && ok "drools-alphanetwork-compiler/src/main/java/org/drools/ancompiler/KieBaseUpdaterANCFactory.java" \\
  || miss "missing critical file: drools-alphanetwork-compiler/src/main/java/org/drools/ancompiler/KieBaseUpdaterANCFactory.java"
test -f "build-parent/pom.xml" \\
  && ok "build-parent/pom.xml" \\
  || miss "missing critical file: build-parent/pom.xml"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 30 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~0d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/apache/incubator-kie-drools"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Drools is a Java-based rule engine, DMN (Decision Model and Notation) engine, and complex event processing (CEP) engine that executes business rules with forward-chaining and backward-chaining inference. It allows developers to externalize business logic from application code and evaluate complex conditions, events, and decision models at runtime with high performance through optimized data structures like the Rete algorithm and alpha network compilation. Multi-module Maven monorepo organized by capability: bom/ contains Bill-of-Materials POM files for different subdomains (drools-bom, kie-dmn-bom, kie-pmml-bom, kie-efesto-bom), build-parent/ defines shared build configuration, drools-alphanetwork-compiler/ implements the Rete network compiler in Java, with language grammars defined in ANTLR (.g4 files). CI orchestration uses .ci/buildchain-config.yaml for test matrix coordination.

Enterprise Java developers and architects building decision support systems, policy engines, and real-time event processing applications who need to decouple business rules from code; business analysts who author rules in DSL form; and organizations requiring DMN standard compliance for decision automation.

Highly mature and production-ready. This is an Apache incubator project with 50MB+ of Java code, comprehensive CI/CD via GitHub Actions (.github/workflows/ci.yaml, pr-downstream.yml), multiple BOM modules for dependency management, explicit locale-aware test profiles (test-en), and careful license header checking—indicating long-term active maintenance and enterprise usage.

Low risk for core functionality but moderate complexity. The codebase is split across multiple specialized modules (drools-alphanetwork-compiler, kie-dmn-bom, kie-pmml-bom) with interdependencies; ANTLR parser generation (102KB) adds compilation complexity; and the requirement to set -Dfile.encoding=UTF-8 and run locale-specific tests suggests platform compatibility concerns. Check last commit dates and open issue backlog on GitHub.

Active development with recent PR-based CI setup (pr-drools.yml, pr-downstream-full.yml), split-package detection enforcement (split-package-detection.yml), and OpenRewrite rule configuration (.openrewrite/rewrite.yml) suggesting ongoing modernization. The .git-blame-ignore-revs file indicates recent large refactorings; buildchain project dependencies (buildchain-project-dependencies.yaml) suggest coordination with related KIE ecosystem projects.

git clone https://github.com/apache/incubator-kie-drools.git
cd incubator-kie-drools
mvn clean install
# For non-en_US locale:
mvn clean install -Ptest-en
# Set MAVEN_OPTS if encountering UnmappableCharacterException:
export MAVEN_OPTS="-Dfile.encoding=UTF-8"
mvn clean install

Daily commands: This is a library, not a standalone service. Build with mvn clean install (or make test using the Makefile). Execute tests with mvn test or make test. Locale-specific test execution: make test -Ptest-en or mvn test -Ptest-en.

• bom/pom.xml — Root Bill of Materials defining all dependency versions across the entire Drools ecosystem; any version conflict or update must start here.
• drools-base/src/main/java/org/drools/base/RuleBase.java — Core abstraction representing the compiled rule set that all rule engines delegate to; essential for understanding rule execution flow.
• drools-alphanetwork-compiler/src/main/java/org/drools/ancompiler/ObjectTypeNodeCompiler.java — Central compiler that transforms Rete network alpha nodes into optimized bytecode; critical performance path for rule matching.
• drools-alphanetwork-compiler/src/main/java/org/drools/ancompiler/KieBaseUpdaterANCFactory.java — Factory pattern implementation for creating and registering compiled alpha network updaters; controls plugin architecture for rule compilation.
• build-parent/pom.xml — Parent POM that configures build plugins, compiler settings, and quality gates for the entire monorepo.
• .github/workflows/ci.yaml — Main CI/CD pipeline defining test suites, build verification, and deployment gates that protect code quality.

Add a new compilation handler for a rule element type

1. Create new handler class extending AbstractCompilerHandler (drools-alphanetwork-compiler/src/main/java/org/drools/ancompiler/AbstractCompilerHandler.java)
2. Implement handle() method to process AST nodes and generate bytecode (drools-alphanetwork-compiler/src/main/java/org/drools/ancompiler/NetworkHandler.java)
3. Register handler in ObjectTypeNodeCompiler to invoke during compilation (drools-alphanetwork-compiler/src/main/java/org/drools/ancompiler/ObjectTypeNodeCompiler.java)
4. Add unit tests verifying handler behavior with test facts (drools-alphanetwork-compiler/src/test/java/org/drools/ancompiler/BaseModelTest.java)

Add a new optimization to the alpha network compiler

1. Extend PropagatorCompilerHandler or create new handler for optimization logic (drools-alphanetwork-compiler/src/main/java/org/drools/ancompiler/PropagatorCompilerHandler.java)
2. Implement CanInlineInANC interface to determine when optimization applies (drools-alphanetwork-compiler/src/main/java/org/drools/ancompiler/CanInlineInANC.java)
3. Add integration test with realistic rule sets to validate correctness (drools-alphanetwork-compiler/src/test/java/org/drools/ancompiler/MixedConstraintsTest.java)
4. Benchmark against LargeAlphaNetworkTest to ensure no performance regression (drools-alphanetwork-compiler/src/test/java/org/drools/ancompiler/LargeAlphaNetworkTest.java)

Add a new indexable constraint type

1. Define constraint AST node in ObjectTypeNodeParser (drools-alphanetwork-compiler/src/main/java/org/drools/ancompiler/ObjectTypeNodeParser.java)
2. Implement HashedAlphasDeclaration for hash-based index generation (drools-alphanetwork-compiler/src/main/java/org/drools/ancompiler/HashedAlphasDeclaration.java)
3. Add test case covering single and multiple constraints of new type (drools-alphanetwork-compiler/src/test/java/org/drools/ancompiler/MultipleIndexableConstraintsTest.java)
4. Update RangeIndexANCTest if constraint supports range operations (drools-alphanetwork-compiler/src/test/java/org/drools/ancompiler/RangeIndexANCTest.java)

• Java/JVM — Bytecode generation and runtime compilation via Javassist/ASM require JVM; enables cross-platform rule engines with shared class format
• Maven — Multi-module monorepo with complex cross-module dependencies requires sophisticated dependency management and Bill of Materials pattern
• Rete algorithm (alpha/beta networks) — Efficient incremental rule matching with hash-indexed alpha nodes for O(1) constraint evaluation vs O(n) interpretation
• Dynamic bytecode compilation — Trades compilation time for dramatic runtime performance gains; removes interpreter overhead for rule evaluation

• Alpha network compilation to bytecode vs interpreted rule execution

  • Why: Startup compilation cost amortizes across many rule evaluations; improves throughput for high-frequency matching scenarios
  • Consequence: Increased memory footprint from generated classes; slower single-rule-fire scenarios; requires JVM with dynamic compilation support

• Hash-indexed alpha nodes vs tree-based discrimination networks

  • Why: Hash indexing provides O(1) lookup for equality constraints on frequently-tested fields
  • Consequence: Range constraints require fallback to linear scan; memory overhead for hash tables; cache misses on sparse domains

• Monorepo structure with shared BOM vs decoupled modules

  • Why: Ensures version consistency across rule engine, DMN engine, and CEP engine; simplifies cross-cutting concerns (licensing, build quality)
  • Consequence: Tightly coupled release cycles; larger clone/build footprint; PR review complexity due to cross-module changes

• Does not provide a REST API or server endpoint—Drools is an embedded library, not a standalone service
• Does not implement authentication or authorization—security is the embedding application's responsibility
• Does not support horizontal scaling or distributed rule execution—single-JVM or embedded cluster only

1. Locale sensitivity: Many tests require en_US locale; default builds may fail on non-English systems without -Ptest-en profile. 2. File encoding: Must set MAVEN_OPTS=-Dfile.encoding=UTF-8 in environment, not as mvn argument, or UnmappableCharacterException occurs. 3. Multi-module dependency order: BOM modules have interdependencies (kie-core-bom is parent); building individual modules without parent may fail. 4. ANTLR regeneration: Grammar changes require parser regeneration; manual steps may be needed if IDE doesn't trigger Maven goal. 5. Buildchain coordination: .ci/buildchain-config.yaml indicates tests depend on external KIE ecosystem projects; standalone builds may not test full integration.

• Rete Algorithm — The core pattern-matching engine in Drools that optimizes rule evaluation by maintaining a network of condition nodes—essential to understanding why Drools is fast for thousands of rules.
• Forward Chaining — Drools uses forward chaining (data-driven inference) as its primary execution mode—understanding the difference from backward chaining explains how rules fire when new facts arrive.
• Complex Event Processing (CEP) — Drools includes CEP capabilities for temporal rule patterns (e.g., 'Event B must occur within 5 seconds of Event A')—this is a key differentiator for real-time systems.
• DMN (Decision Model and Notation) — Drools implements the OMG DMN standard for declaring decision logic in a standardized, non-code format—understanding DMN structure is crucial for users writing decision tables in Drools.
• Alpha Network Compilation — The drools-alphanetwork-compiler module compiles rule conditions into optimized bytecode—knowing this exists explains the ANCConfiguration class and why rule performance varies.
• Bill of Materials (BOM) Pattern — The bom/ directory uses Maven BOM pattern (dependency management without code)—understanding this explains why drools-bom, kie-dmn-bom, etc. exist and how version alignment works.
• ANTLR Parser Generation — Drools' rule syntax is compiled from ANTLR grammars (102KB in repo)—understanding this explains build-time parser generation and why grammar changes require recompilation.

• kiegroup/drools — The original Drools repository (before Apache incubation)—may contain historical context and issues.
• apache/incubator-kie-optaplanner — Companion KIE project for constraint satisfaction and optimization, often used with Drools rules for complex decision problems.
• apache/incubator-kie-kogito — Runtime engine that can execute Drools rules and DMN models; integrates Drools as a core decision component.
• openrewrite/rewrite — The OpenRewrite framework used in .openrewrite/rewrite.yml for automated code refactoring and modernization.
• antlr/antlr4 — ANTLR4 parser generator used for Drools rule syntax compilation (102KB of ANTLR grammars in codebase).

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for AlphaNetworkCompiler with various rule patterns

The drools-alphanetwork-compiler module has multiple handler classes (AssertHandler, ModifyHandler, NetworkHandler, etc.) but there's no visible test directory in the file structure. This compiler is critical for rule engine performance. New contributors could add comprehensive integration tests covering different rule patterns, inline conditions, and edge cases to ensure the compiler correctly handles various DRL constructs.

• [ ] Create drools-alphanetwork-compiler/src/test/java directory structure
• [ ] Write tests for ObjectTypeNodeCompiler with different field reference patterns
• [ ] Add tests for AssertHandler and ModifyHandler with complex rule conditions
• [ ] Create tests for CanInlineInANC to verify inlining decision logic
• [ ] Add regression tests for CompiledNetworkSources generation with different rule topologies

Create automated GitHub Action workflow for dependency vulnerability scanning

While .github/dependabot.yml exists for dependency updates, there's no visible CI workflow specifically for scanning transitive dependencies for known vulnerabilities (CVEs). Given this is a core rule engine used in production systems, adding a dedicated security scanning workflow would be valuable. This could use tools like OWASP Dependency-Check or GitHub's native vulnerability detection.

• [ ] Create .github/workflows/security-scan.yml workflow file
• [ ] Integrate OWASP Dependency-Check Maven plugin into build-parent/pom.xml
• [ ] Configure the workflow to run on pushes to main and all PRs
• [ ] Add failure conditions for HIGH/CRITICAL severity vulnerabilities
• [ ] Create SECURITY.md documenting the scanning process and how to report vulnerabilities

Add documentation and tests for alpha-network compiler configuration options (ANCConfiguration)

The ANCConfiguration.java class exists but there's no visible documentation about its configuration options or test coverage. Contributors could document all available configuration parameters, create unit tests for each configuration scenario, and add examples to help users optimize alpha-network compilation for their use cases.

• [ ] Create drools-alphanetwork-compiler/src/test/java/.../ANCConfigurationTest.java with comprehensive test cases
• [ ] Document all ANCConfiguration properties in a new docs/alpha-network-compiler-config.md file
• [ ] Add examples showing performance implications of different configuration combinations
• [ ] Write tests for KieBaseUpdaterANCFactory to verify configuration propagation
• [ ] Add JavaDoc improvements to ANCConfiguration and related classes

• Add missing JavaDoc to drools-alphanetwork-compiler/src/main/java/org/drools/ancompiler/ classes—the core alpha network optimizer lacks developer documentation explaining the Rete optimization strategy.: Low risk, high learning value; helps future contributors understand the performance-critical path.
• Create locale-aware test examples for non-en_US environments in the test-en profile—currently only mentioned in README but no sample test class demonstrates the pattern.: Addresses the locale sensitivity trap and helps future developers add locale tests without guessing.
• Document the BOM hierarchy in bom/README.md—explain why drools-bom, kie-dmn-bom, kie-pmml-bom, and kie-efesto-bom exist separately and when to use each.: New contributors struggle with multi-module structure; clear docs reduce onboarding friction.

The Apache Drools project shows a generally reasonable security posture as an open-source Apache Foundation project. However, there are concerns regarding incomplete dependency files preventing full vulnerability analysis, lack of visible automated security scanning in CI/CD pipelines, and absence of a security disclosure policy. The codebase appears well-structured with proper licensing headers. Primary recommendations: (1) Complete and validate all POM files, (2) integrate SAST/DAST tools in CI/CD, (3) establish formal security reporting procedures, (4) regularly perform dependency audits. No critical or obviously exploitable vulnerabilities were identified based on the provided file structure, but a deeper code review would be needed for injection risks in the rule engine components.

• Medium · Incomplete POM File — bom/drools-bom/pom.xml. The bom/drools-bom/pom.xml file appears to be truncated or malformed. The closing tag for issueManagement is incomplete ('issueManagem' instead of 'issueManagement>'). This could indicate a corrupted build configuration or incomplete repository state. Fix: Verify the integrity of the POM file by checking the repository's git history. Rebuild the file by ensuring all XML tags are properly closed and validated against Maven schema.
• Low · Potential XXE Vulnerability in XML Processing — Multiple POM files and potential XML parsing in drools-alphanetwork-compiler. The codebase uses Maven POM files which parse XML. While the file structure doesn't show direct unsafe XML parsing, the presence of incomplete POM files and multiple XML configurations warrants review. If XML parsers are not properly configured to disable external entity resolution, XXE attacks could be possible. Fix: Ensure all XML parsers are configured to disable XXE processing by setting FEATURE_SECURE_PROCESSING to true and disabling DOCTYPE declarations in any custom XML handling code.
• Low · Dependency Management Review Needed — bom/drools-bom/pom.xml and other BOM files. The dependency file provided is incomplete (cut off at 'issueManagem'). This prevents comprehensive analysis of all declared dependencies. Known vulnerable versions of transitive dependencies could exist without being detected. Fix: Run 'mvn dependency:tree' and 'mvn org.owasp:dependency-check-maven:check' to identify all dependencies and check for known vulnerabilities. Regularly update dependencies and use Maven's enforcer plugin to enforce dependency convergence.
• Low · No Evidence of Security Headers in CI Configuration — .github/workflows/. Review of GitHub Actions workflow files (.github/workflows/*.yml) shows CI/CD pipeline configuration. No explicit security scanning (SAST/DAST) or dependency vulnerability scanning is evident from the file structure. Fix: Integrate automated security scanning tools in CI/CD pipeline such as: OWASP Dependency-Check, Snyk, GitHub Advanced Security (CodeQL), or SonarQube to detect vulnerabilities early in development.
• Low · No SECURITY.md File Found — Repository root. Best practice for open source projects is to maintain a SECURITY.md file documenting vulnerability reporting procedures. This file is not present in the repository root. Fix: Create a SECURITY.md file documenting: responsible disclosure policy, supported versions, how to report security vulnerabilities, and security update process. Reference: https://securitymd.readthedocs.io/

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.