Agent Guide for Apache Unomi

This file is read by automated agents (security scanners, code analyzers, AI assistants) operating on this repository.

Security

Security model: SECURITY.md

Agents that scan this repository should consult SECURITY.md and the threat model it links before reporting issues.

Branch backporting (generic)

When porting changes from a source branch to a target branch, follow .cursor/rules/branch-backport.mdc. Summary:

  1. Target is canonical for files that already exist there — branch from origin/<target>, not from source.
  2. Target may be ahead — merged review PRs on the target often improve code beyond the source. A diff ≠ missing feature.
  3. Commit history on the target — for each existing file: git log origin/<source>..origin/<target> -- <path>. Non-empty output means target-only fixes you must not drop.
  4. Never blind-checkout existing files from source (git checkout origin/<source> -- <path>). Port additive hunks only.
  5. Audit before commit — diff regression scan plus history cross-check; use git blame origin/<target> on any line you remove.
  6. Classify paths: ADD (new on target) · MODIFY (hand-merge from target) · MERGE (build/CI/deps — target wins on target-only lines).
  7. Do not bulk-cherry-pick from source branch history without per-commit review.

Cursor rule: .cursor/rules/branch-backport.mdc

Backporting unomi-3-dev → master (UNOMI-875)

Backport phase complete (Phase 2 mega-PRs + #791 final hygiene + #819 3-dev closure, July 2026). Apply generic rules above for any future cherry-picks; see .cursor/rules/unomi-3-dev-backport.mdc for standing exclusions.

Source (archived)Tag unomi-3-dev-archive-2026-07 @ eca005fd8 — remote branch deleted
Targetmaster
Active local plan.local-notes/unomi-3.1-remaining-work-plan.md
Archived backport plans.local-notes/archive/ (Phase 1, Phase 2, #757 stack tracker)

To inspect the archived tip:

git fetch origin tag unomi-3-dev-archive-2026-07
git diff master...unomi-3-dev-archive-2026-07 -- <path>

Unomi-specific reminders:

  • Master is ahead on REST mappers, tracing, shell CRUD (#755, #763), CI (#780, #957), docker image pins — do not revert.
  • Safe wholesale adds: new scripts, Postman, docs, new Java classes.
  • Do not port: migration scripts (UNOMI-943), 3-dev REST mappers, security WIP, wholesale test harness from 3-dev.
  • Remaining 3.1 work: UNOMI-960 (Javadoc / PR10) — not a 3-dev backport.