@jahia/agentic 0.1.0 → 0.2.0

package/dist/cursor/.agents/skills/jahia-java-osgi/SKILL.md

@@ -0,0 +1,134 @@
+---
+name: jahia-java-osgi
+description: OSGi component patterns for Jahia Java development — correct usage of @Component lifecycle, @Reference, Export-Package, whiteboard services, and thread safety. Covers both the right approach and the pitfalls that cause NPEs, stale state, or leaked internals. Load when implementing or reviewing any class annotated with @Component, @Reference, or @Activate.
+allowed-tools: Read
+---
+
+# OSGi Component Patterns for Jahia Java
+
+This skill covers how to write OSGi components correctly in a Jahia Java module. Each section states the correct approach first, then the pitfall to avoid. Both developers and reviewers use this skill.
+
+For broader Java concurrency patterns (atomic variables, locking, thread-safe collections, `ThreadLocal`, JCR session threading) that apply beyond OSGi components, load `/jahia-java-concurrency`.
+
+For a comprehensive OSGi reference (bundle lifecycle, Blueprint XML, Karaf tooling, service registry), load the `jahia-dev-java` skill and read `references/osgi.md`.
+
+---
+
+## Component state and configuration reload
+
+### Correct approach
+
+`@Component` services are singletons. Configuration is delivered via `@Activate` (on first start) and `@Modified` (on config change). `@Modified` runs on a different thread than service consumers.
+
+The safe pattern for config reload:
+
+```java
+private volatile Config config;
+
+record Config(String host, int port) {}
+
+@Activate @Modified
+public void activate(MyOsgiConfig cfg) {
+    this.config = new Config(cfg.host(), cfg.port());
+}
+
+public void doWork() {
+    var c = this.config; // snapshot once — atomic read
+    // use c.host(), c.port() ...
+}
+```
+
+A single `volatile` write (the reference swap) is atomically visible to all readers. Readers snapshot the reference once at method entry and work with the snapshot — they never see a half-updated config.
+
+### Pitfalls
+
+- **Mutable fields updated in `@Activate`/`@Modified` without `volatile` or synchronization.** A consumer thread can read a field while `@Modified` is updating it — data race. P1 finding.
+- **Multiple fields updated individually without synchronization.** Even with `volatile`, two separate field reads can see values from different config snapshots. Use a single `volatile Config` record, not individual `volatile String host; volatile int port`.
+
+---
+
+## Service references
+
+### Correct approach
+
+- `@Reference` fields are set by SCR before `@Activate`. Treat them as effectively final inside the component's methods.
+- For **mandatory** references (`cardinality = MANDATORY`), the component will not activate if the service is absent — null checks are not needed.
+- For **optional** references (`cardinality = OPTIONAL`), the field can be `null` — always guard.
+- For **dynamic** references (`policy = ReferencePolicy.DYNAMIC`), the field can be replaced at runtime. Snapshot it at method entry: `var svc = this.myService;` then use `svc`. Reading the field twice risks NPE if the service is unregistered between reads.
+
+### Pitfalls
+
+- **Non-mandatory `@Reference` accessed without null guard.** P1 — NPE in production when the referenced bundle is not deployed.
+- **Dynamic reference read twice without snapshot.** Between two reads the SCR may set the field to `null`. P1.
+- **`policyOption = GREEDY`.** SCR rebinds to a higher-ranked service when one appears. Code holding a reference to the old service instance keeps using a deactivated service. Document this if intentional.
+
+---
+
+## Lifecycle side effects
+
+### Correct approach
+
+Every side effect created in `@Activate` must be undone in `@Deactivate`. Components can be deactivated and re-activated on config changes (depending on `@Modified` policy). Failing to undo side effects causes them to accumulate across activations.
+
+Checklist:
+- Thread started in `@Activate` → stopped in `@Deactivate` (interrupt + join).
+- JCR event listener registered → unregistered.
+- Scheduled task registered → cancelled.
+- External connection opened → closed.
+- Cache populated → cleared or reseeded.
+
+### Pitfall
+
+A listener registered in `@Activate` but never unregistered in `@Deactivate` survives deactivation, fires events for a component that is no longer active, and duplicates on next activation. P1.
+
+---
+
+## Export-Package hygiene
+
+### Correct approach
+
+`Export-Package` in `pom.xml` defines what other bundles can import. It is the module's public API contract.
+
+- Export only interfaces and types in a dedicated `api` or `spi` sub-package.
+- Never export `*.impl`, `*.internal`, `*.actions` — the name signals private scope.
+- Never re-export third-party packages.
+- If the module advertises an SPI for external consumers, the SPI should live in a **separate Maven module** (`{name}-api`). Changing the runtime JAR then does not force a version bump on the API.
+
+### Pitfall
+
+Exporting implementation packages means any other bundle can import your internal classes. A refactor that renames or removes an internal class becomes a breaking change for dependent bundles. P1.
+
+---
+
+## Whiteboard pattern services
+
+Services registered as `@Component` — `Servlet`, `Filter`, `EventHandler`, GraphQL provider — are activated the moment the bundle starts. If the service is reachable over HTTP, it is as exposed as a `web.xml` servlet, with no extra protection by default. Apply the security mapping from `jahia-java-security` for every HTTP-reachable whiteboard service.
+
+---
+
+## Service locator anti-pattern
+
+### Correct approach
+
+Declare all dependencies as `@Reference` fields. SCR injects them before `@Activate`. The component's constructor or `@Activate` method has all dependencies available without any lookup.
+
+### Pitfall
+
+```java
+// anti-pattern — service locator inside a method
+MyService svc = (MyService) SpringContextSingleton.getBean("myService");
+```
+
+Service locator calls inside methods: hide the component's real dependencies, make the code impossible to unit-test, bypass SCR lifecycle guarantees, and can return stale or wrong beans after a context refresh. P2 in general code; P1 in a hot path or security-relevant method.
+
+---
+
+## Thread safety summary for reviewers
+
+When reviewing an `@Component` service, ask:
+
+1. Are there mutable instance fields? If yes — are they `volatile` or synchronized?
+2. Does the component react to `@Modified`? If yes — do consumers snapshot config at method entry?
+3. Are there `DYNAMIC` references? If yes — do callers snapshot the reference?
+4. Does the component start threads, register listeners, or open connections? If yes — does `@Deactivate` undo all of them?
+5. Does the component's Javadoc state its thread-safety contract? If the service is not internally safe, the caller must be told what external serialization is required.

package/dist/cursor/.agents/skills/jahia-java-persistence/SKILL.md

@@ -0,0 +1,177 @@
+---
+name: jahia-java-persistence
+description: Persistence and data model patterns for Jahia Java backend — correct usage of JPA/Hibernate with JCR, N+1 avoidance, timestamp consistency, entity model decisions, transactional asymmetry between SQL and JCR, and locking/concurrency in write paths. Load when implementing or reviewing any class that interacts with a relational database alongside JCR.
+allowed-tools: Read
+---
+
+# Persistence Patterns for Jahia Java Backend
+
+This skill covers how to design and implement the persistence layer correctly when combining SQL (JPA/Hibernate) with JCR in a Jahia Java module. Each section states the correct approach first, then the pitfall. Both developers and reviewers use this skill.
+
+---
+
+## Sequence and counter columns
+
+### Correct approach
+
+Use the database's native mechanisms for generating ordered identifiers:
+- `IDENTITY` / `AUTO_INCREMENT` on the primary key for insertion order.
+- A `SEQUENCE` object (reserved inside a serialized transaction) if you need a stable ordering column separate from the PK.
+
+### Pitfall
+
+```java
+// anti-pattern — read-then-act race
+int max = repository.selectMaxNumber(contentId, locale); // SELECT MAX(...)
+entity.setNumber(max + 1);
+session.persist(entity);
+```
+
+Two concurrent inserts for the same `(contentId, locale)` read the same `MAX`, produce duplicate numbers, and either hit a unique constraint violation or silently corrupt ordering. Application-managed counters are never safe without explicit row-level locking. The counter column is also redundant if the primary key already provides insertion order.
+
+**Finding level:** P1 for concurrent write paths; P2 if access is serialised by a documented higher-level lock, but that invariant must be documented.
+
+---
+
+## N+1 query patterns
+
+### Correct approach
+
+Load parent and child data in one round-trip:
+- SQL: `JOIN` or a `WHERE id IN (...)` batch query.
+- JPA: `JOIN FETCH` in JPQL or `@EntityGraph`.
+
+### Pitfall
+
+```java
+// anti-pattern
+List<Group> groups = repo.listGroups(contentId);       // 1 query
+for (Group g : groups) {
+    g.setVersions(repo.loadVersionsForGroup(g.getId())); // N queries
+}
+```
+
+N+1 patterns are invisible in low-volume testing but degrade linearly under real content volumes. For unbounded lists (version history, publication logs) this becomes a UI performance cliff.
+
+**Finding level:** P2 for capped lists; P1 for unbounded lists in hot paths.
+
+---
+
+## Timestamp consistency in batch operations
+
+### Correct approach
+
+Compute the timestamp **once** at the start of a logical operation and pass it to every entity created by that operation:
+
+```java
+Instant now = Instant.now(); // computed once
+groupEntity.setCreatedAt(now);
+for (var version : versions) {
+    versionEntity.setCreatedAt(now); // same value for all
+}
+```
+
+This makes "all entities from this operation" a trivial equality predicate: `WHERE operationId = ? AND createdAt = ?`. It also makes the audit trail semantically correct — these are one logical event, not N sequential events.
+
+### Pitfall
+
+Multiple independent `Instant.now()` calls within the same logical operation produce timestamp drift. Even millisecond drift means "show me all versions from this publish event" requires a range query with fuzzy bounds instead of equality. It also implies false ordering between things that are the same event.
+
+**Finding level:** P2 — correctness and query simplicity. Elevate to P1 if the drift creates misleading audit trails.
+
+---
+
+## Entity model: when a separate table earns its keep
+
+### Correct approach
+
+A separate table/entity is justified when it carries state that would be annoyingly denormalised across every member row: operation type, author, workflow status, retry counters, approval metadata, referential integrity constraints.
+
+If the only purpose of the separate table is to group rows (no meaningful payload of its own), a plain `operationId` UUID column on the member table is sufficient:
+- "All operations for a content": `SELECT DISTINCT operationId, createdAt FROM NodeVersion WHERE contentId = ? ORDER BY createdAt DESC`
+- "All versions of one operation": `SELECT * FROM NodeVersion WHERE operationId = ?`
+
+Rule of thumb: defer extraction to a separate entity until the denormalised columns exceed 3–4 fields, or you need referential integrity on the operation itself (cascading, per-operation locks). The refactor is straightforward later — `INSERT ... SELECT DISTINCT` into the new table, add the FK, drop the denormalised columns.
+
+### Pitfall
+
+```java
+// separate table with no meaningful payload — not justified yet
+@Entity class NodeVersionGroupEntity {
+    UUID id;
+    UUID nodeUuid;       // duplicated from every member row
+    Instant createdAt;   // drifts from member rows (see above)
+    // nothing else
+}
+```
+
+A correlation-only entity adds a table, a JOIN on every group query, a separate Hibernate lifecycle, and the risk of timestamp drift — for zero domain benefit until the group gains real state.
+
+**Finding level:** P2 — surface as a design decision for the team, not a demand for immediate refactoring. Ask: does the group entity carry any state today? What is the expected evolution?
+
+---
+
+## Transactional asymmetry — mixed SQL + JCR stores
+
+### Correct approach
+
+SQL (Hibernate) and JCR do not share a transaction. Treat every mixed write path as requiring explicit reasoning about failure modes.
+
+Options in order of preference:
+1. **JCR as system of record:** write to JCR first; only commit to SQL after a successful `session.save()`. If the SQL commit fails, log the orphaned JCR state and add it to a retry or cleanup queue.
+2. **Outbox pattern:** write to SQL only (including a status/outbox column); a separate process reads and applies the JCR write idempotently.
+3. **Accept the asymmetry:** document the inconsistency window explicitly, add a compensating cleanup path, and add monitoring to detect orphaned rows.
+
+### Pitfall
+
+```java
+repository.insertVersion(entity);    // SQL committed inside Hibernate session
+jcrNode.setProperty("...", value);   // if this fails, SQL is already committed
+session.save();
+```
+
+A failure in the JCR write leaves the SQL committed and the JCR unchanged — silent data inconsistency. Symptoms: rows in the DB with no corresponding JCR node, or vice versa.
+
+**Finding level:** P1 — silent data inconsistency. Elevate to P0 if the inconsistency is user-visible or hard to detect.
+
+---
+
+## Locking and write paths
+
+### Correct approach
+
+Document the thread-safety contract of every write path that involves locking, restoration, or multi-step state transitions:
+- Is the path safe to call concurrently? If not, what external lock must the caller hold?
+- Does the path clear existing locks? If yes, whose lock? Under what conditions is clearing safe?
+
+Before clearing a JCR lock in a write path:
+1. Verify the lock is not owned by an unrelated operation (active publication job, workflow, concurrent editor).
+2. If the lock is external, fail with a clear error — do not continue.
+
+### Pitfall
+
+```java
+// dangerous — clears all locks unconditionally, continues even if clearing fails
+JCRContentUtils.clearAllLocks(node);
+restoreContent(node, version);
+```
+
+This pattern is dangerous in any path that is not the sole writer. A publication job in progress may have locked the node for a reason; clearing the lock and continuing the restore corrupts the publication. See also `jahia-java-jcr` locking section.
+
+**Finding level:** P0 if active in production code; P1 if guarded by a feature flag off by default — but must appear in known-limitations/next-steps regardless.
+
+---
+
+## Schema documentation
+
+### Correct approach
+
+For any module that introduces relational tables, include a schema summary in `docs/` or a README section covering:
+- Table names and purpose.
+- Key column types and constraints (primary keys, foreign keys, unique constraints, indexed columns).
+- How SQL tables relate to JCR nodes (which JCR property or node UUID maps to which SQL column).
+- Any migration strategy for schema changes.
+
+### Pitfall
+
+Undocumented tables discovered by reviewing Hibernate entity classes alone — reviewers and future maintainers cannot verify the full schema from code without running the application and inspecting the DB. This is a P2 documentation finding.

package/dist/cursor/.agents/skills/jahia-java-security/SKILL.md

@@ -0,0 +1,84 @@
+---
+name: jahia-java-security
+description: Jahia security model for Java backend development — the four protection mechanisms (Security Filter, CSRF Guard, ACLs, captcha), when each applies, and how to audit or implement each correctly. Load when implementing or reviewing any HTTP-reachable surface in a Jahia Java module.
+allowed-tools: Read
+---
+
+# Jahia Security Model for Java Backend
+
+This skill covers how to correctly protect HTTP-reachable surfaces in a Jahia Java module. Each mechanism is described with its correct use, its limits, and the common mistakes that create vulnerabilities. Both developers and reviewers use this skill.
+
+---
+
+## The four protection mechanisms
+
+Every reachable surface in a Jahia module is protected by zero, one, or several of these. Map each one explicitly for any surface you implement or review.
+
+### 1. Jahia Security Filter (API scopes)
+
+- **What:** OSGi-configurable filter that gates URL patterns by `Origin`/`Referer` and required permissions/scopes.
+- **Config:** YAML under `META-INF/configurations/org.jahia.modules.api.permissions-*.yaml`.
+- **Origin gating:** `auto_apply: - origin: hosted` ensures requests come from the same domain. Works for guests and authenticated users. Does not break CDN caching.
+- **Permission gating:** `grants: - api: <name>; node: <selector>` enforces a Jahia permission.
+- **When to use:** default protection for any module-exposed servlet or GraphQL endpoint reachable over HTTP. This is the first line of defense — apply it before considering CSRF Guard or inline checks.
+
+### 2. CSRF Guard
+
+- **What:** Jahia-wide servlet filter injecting a token into XHR/fetch and validating it server-side.
+- **Critical limitation:** `jahia.csrf-guard.bypassForGuest = true` by default. CSRF Guard **does not protect guest submissions** out of the box. Enabling it for guests breaks CDN caching of public pages.
+- **When to use:** authenticated-only operations where you can verify the URL pattern is in the guard's `resolvedUrlPatterns` config.
+- **Common mistake:** assuming CSRF Guard protects a guest-reachable form. It does not — a guest submitting a public form bypasses CSRF Guard entirely.
+
+### 3. Jahia permissions and ACLs
+
+- **What:** JCR-based ACLs + named permissions declared in `permissions.xml` or `*.cnd`.
+- **Enforcement:** `JCRSessionWrapper` (user session — permissions apply) vs `JCRSessionFactory.getCurrentSystemSession()` / `JCRTemplate.doExecuteWithSystemSession` (system session — permissions bypassed).
+- **GraphQL:** `@GraphQLField` operations should declare `@RequirePermission` annotations. An admin operation without `@RequirePermission` is a finding.
+- **When to use:** any operation that reads/writes JCR content with content-level access rules — jContent admin screens, content workflows, operations that respect site/node permissions.
+- **Audit rule:** when code uses a system session, the security boundary is whatever check happened *before* the `doExecuteWithSystemSession` call. Find that check explicitly. If there is none, the operation is anonymous-privileged — P0 for writes, P1 for reads.
+
+### 4. Captcha and one-time tokens
+
+- **What:** non-replayable credentials tied to the rendering page.
+- **When to use:** defense-in-depth against bots and as partial CSRF mitigation for guest forms.
+- **Not a primary CSRF control.** Captcha protects a specific form when enabled, but it is not origin verification. Do not let a code path rely on captcha alone.
+
+---
+
+## Decision matrix
+
+For each surface you implement or review, fill this in:
+
+| Surface | Guests? | Auth users? | Side effects? | Required protection |
+|---|---|---|---|---|
+| Public form submit | Yes | Yes | Email, JCR write | Security Filter `origin: hosted` (primary) + captcha (defense-in-depth) |
+| Admin GraphQL query | No | Yes (with permission) | Read JCR | Security Filter `origin: hosted` + `@RequirePermission(...)` |
+| Admin GraphQL mutation | No | Yes (with permission) | Write JCR | Same + verify ACL when system session is used |
+| OSGi servlet at `/modules/...` | Depends | Depends | Depends | At minimum: `origin: hosted` |
+| Choicelist initializer | Indirect (editor UI) | Yes (editor) | Read config | Inherits editor auth — verify it does not leak cross-tenant data |
+
+---
+
+## Implementing a secure surface — checklist
+
+When adding a new servlet, GraphQL operation, or filter:
+
+1. **Declare the Security Filter scope** in `org.jahia.modules.api.permissions-*.yaml`.
+2. **Classify the surface** in the decision matrix above.
+3. **If writing JCR with a system session:** document the prior permission check in a Javadoc comment on the method.
+4. **If the surface is public (guest-reachable):** do not rely on CSRF Guard alone. Use `origin: hosted` + captcha if the action has side effects.
+5. **If the surface is admin-only:** add `@RequirePermission` to the GraphQL field or inline `JCRTemplate` ACL check.
+6. **Document the intent.** A deliberate "this endpoint is public because X" must be in a Javadoc on the class or in `docs/security.md`. An undocumented gap is a finding even if intentional — the next maintainer cannot tell intent from accident.
+
+---
+
+## Findings to surface during review
+
+1. **Unprotected endpoint.** Any servlet/GraphQL operation without a Security Filter scope **and** without `@RequirePermission` **and** without an inline auth check. P0 unless explicitly documented as intentionally public.
+2. **CSRF Guard guest bypass misunderstood.** Code or docs claiming CSRF Guard protects guests. P0 — foundational misunderstanding.
+3. **System session without prior permission check.** P0 for writes, P1 for reads.
+4. **Captcha presented as primary CSRF defense.** P1 — it is defense-in-depth, not primary.
+5. **Missing `@RequirePermission` on admin GraphQL.** P0 for mutations, P1 for sensitive-data queries.
+6. **Permission referenced but not declared.** A permission name used in code or config that is not declared in any module resource. P1.
+7. **Email recipients from user input.** Any `to:` address derived from a submitted field without an allowlist. P1 — open relay vector.
+8. **Outbound HTTP without timeouts.** `HttpClient.newHttpClient()` with no `connectTimeout` or request timeout on any external call. P0 — trivial DoS.

package/dist/cursor/.agents/skills/jahia-review-java/SKILL.md

@@ -0,0 +1,131 @@
+---
+name: jahia-review-java
+description: Reviews a Jahia Java/backend module (or PoC) across 6 passes — security, code health, build/packaging, documentation drift, tests, and consolidation. Produces a prioritised finding report with concrete next steps. Load supporting references from this skill's references/ folder on demand.
+allowed-tools: Bash, Read
+---
+
+# Skill: jahia-review-java
+
+You are a senior Java/Jahia reviewer. Audit a Jahia Java module (OSGi, JCR, CND, Spring) or a PoC branch and produce a code review that is **actionable, prioritised, and reusable as input for the next review cycle**.
+
+## What "good" looks like
+
+1. **Security-first.** Every endpoint, servlet, GraphQL operation, action is mapped to its access control posture.
+2. **Concise with a path forward.** Each finding names the problem, names the fix, names the effort. No hedging.
+3. **No noise.** Style, formatting — out. Findings must survive "why does this matter for production?"
+4. **Honest about uncertainty.** When you cannot verify a claim, say so and flag for the author.
+5. **Reusable next cycle.** Output structure is stable so the next reviewer can see what was fixed, deferred, or new.
+
+## Operating modes
+
+Detect from context. Ask once if genuinely ambiguous.
+
+| Mode | Trigger | Output |
+|---|---|---|
+| **PR review** | GitHub MCP available + PR diff in context | Inline PR comments + one summary comment with the prioritised table |
+| **Module audit** | Checked-out source, no PR context | Single `code-review-{module}-{YYYY-MM-DD}.md` at repo root |
+| **PoC review** | PR/branch explicitly described as a PoC | Surface risks, missing next steps, and unknowns — not a production readiness checklist |
+| **Follow-up** | A prior `code-review-*.md` exists in the repo | Update the prior doc in place — mark each finding resolved / deferred / still-open |
+
+**PoC mode distinction:** A PoC review does not expect production-grade code. Its goal is to surface every risk, weak spot, missing business logic, and open architectural question so the team can make informed decisions before committing to the implementation. Frame each finding as "next step: team decision" rather than demanding immediate fixes. The PoC owner is not expected to have all the answers.
+
+## The review passes — execute in order
+
+### Pass 0 — Orient (never skip)
+
+- List the source tree; identify packages by responsibility (servlets, actions, services, GraphQL, filters, OSGi components, persistence).
+- Read `pom.xml`, `AGENTS.md` (if present), `README.md`, all files under `docs/` and `.harness/`.
+- Read every CND file; note declared node types, mixins, namespace.
+- Identify SPI surface: `Export-Package` in `pom.xml`, public interfaces, `@ProviderType` annotations.
+- Note prior reviews. If one exists, switch to follow-up mode.
+
+Output of this pass stays internal — it is your map, not written to the review.
+
+### Pass 1 — Security surface mapping
+
+For every reachable surface (servlet, JAX-RS, GraphQL query/mutation, whiteboard service, filter, choicelist initializer):
+
+1. **Who can reach it?** Guest / authenticated / role-gated / permission-gated / internal-only.
+2. **What does it do?** Read, write, side-effect (email, HTTP, file I/O), admin operation.
+3. **How is access enforced?** Security Filter scope, CSRF Guard, `@RequirePermission`, inline ACL, session-based, none.
+4. **Is the posture documented?** A deliberate "unprotected because X" is acceptable. An undocumented gap is a finding.
+
+Cross-reference with `/jahia-java-security` for Jahia-specific mechanisms and the full decision matrix.
+
+### Pass 2 — Code health
+
+Walk the implementation. Look for:
+
+- **Layering violations.** Business logic in servlets. JCR access bypassing services. Presentation in the service layer.
+- **Oversized classes.** One class doing 5+ jobs. Each responsibility is a candidate for extraction.
+- **Reinvention.** Hand-rolled encoding, escaping, date parsing where `java.time`, Commons Lang, or Guava would do it.
+- **Overdesign.** Premature abstraction with one implementation. SPI hooks no consumer exists for. Factory+builder+strategy for a 30-line operation. Flag P3 unless it blocks understanding.
+- **Concurrency.** Mutable fields in `@Component` services without `volatile`. Services that are not internally thread-safe but carry no documentation of caller responsibility. Read-then-act DB patterns (`SELECT MAX` + `INSERT` without serialisation). Restore/write paths that bypass or unconditionally clear caller-set locks.
+- **Persistence anti-patterns.** N+1 queries. Separate tables with no attributes of their own (a correlation UUID on the row is enough). Application-managed counters instead of DB-native auto-increment. Multiple independent `Instant.now()` calls in the same logical operation (timestamp drift). Transactional asymmetry between SQL and JCR commits.
+- **Error handling.** Swallowed exceptions. Fail-open on infrastructure errors. Exception in a side-effect that can abort an unrelated primary operation.
+- **TODOs and leftovers.** `TODO`, `FIXME`, `XXX`, commented-out code. Each is a finding unless tracked in `docs/` or explicitly accepted in the PR description.
+- **Dead payload fields.** Fields stored in the persistence model but never read by any live code path — flag as dead storage; remove or document intent.
+- **Diff/delta engine gaps.** When a reverse-delta engine is present: check what entity state is NOT diffed (mixins, children, ACLs, references). Verify empty-diff short-circuits to avoid phantom versions. Verify old-value storage is actually consumed by the apply path.
+- **Service locator anti-pattern.** `SpringContextSingleton.getBean()` or equivalent inside a service method — prefer `@Reference`/`@Autowired` injection.
+
+Cross-reference with `/jahia-java-jcr` for JCR session, locking, mixin, and SNS pitfalls.
+Cross-reference with `/jahia-java-osgi` for OSGi component lifecycle, reference, and export-package pitfalls.
+Cross-reference with `/jahia-java-persistence` for persistence-layer anti-patterns.
+Cross-reference with `/jahia-java-concurrency` for thread safety — `volatile`, locking, atomics, static fields, JCR session threading.
+
+### Pass 3 — Build, packaging, dependencies
+
+- `jahia-impl` is `<scope>provided</scope>` with all transitives excluded; each used library declared explicitly.
+- `Export-Package` lists only SPI surface, not implementation packages.
+- Embedded libraries are commented in the POM with a *why*.
+- If the module advertises an SPI for third parties, that SPI lives in a separate `*-api` artifact.
+
+### Pass 4 — Documentation drift
+
+Compare every doc, harness file, and `AGENTS.md` claim against the code:
+- URLs, endpoints, class names, config PIDs — do they match?
+- "Not yet implemented" claims for code that is in fact implemented.
+- Known-limitations sections that omit critical risks actually present in the code.
+- Next-steps sections that lack coverage for risks identified in the code.
+
+In PoC mode, the known-limitations/next-steps gap is the primary documentation finding: if the code contains dangerous or incomplete patterns, those must appear in next steps — even if not yet actionable.
+
+### Pass 5 — Tests
+
+1. Is there a `src/test/` directory? If no, list pure-function classes (parsers, validators, calculators) as test targets.
+2. For PoC mode: note which critical paths have no test coverage and which should be added before the PoC direction is validated.
+
+### Pass 6 — Consolidate and prioritise
+
+- Collapse duplicate findings to one finding with multiple sites.
+- Assign severity using the four-level scale below.
+- Assign effort: XS (<1h), S (<half day), M (<2 days), L (more).
+- Sort by severity within sections. Build the prioritised summary table.
+
+## Severity discipline
+
+| Level | When to use |
+|---|---|
+| 🔴 P0 | Active security hole, data loss, fail-open auth, broken public contract, dangerous active code (not just a PoC TODO) |
+| 🟠 P1 | Significant gap defensible only by accepting documented risk, silent partial failure, broken SPI promise |
+| 🟡 P2 | Code health that compounds over time, doc drift, missing tests for critical paths |
+| 🟢 P3 | Refactor opportunities, nice-to-have abstractions, minor cleanup |
+
+When in doubt, drop one level. Inflated severity loses the reader's trust.
+
+## Output
+
+Read `references/code-review-output.md` before writing. It defines section order, finding template, and summary table schema.
+
+Two non-negotiable rules:
+1. **Each finding ends with a concrete next step** — a code change, a ticket, or an explicit "accept as-is, document the tradeoff".
+2. **Surface honest doubts.** When you cannot verify a claim, say so. The author would rather have an explicit unknown than a false certainty.
+
+## What not to do
+
+- Do not lecture. The reader is a senior engineer.
+- Do not flag stylistic preferences unless they map to a configured Checkstyle/PMD rule that would fail CI.
+- Do not invent line numbers. Use `ClassName#methodName` as anchors.
+- Do not pad. If a section has no findings, write "No findings."
+- Do not split one problem into multiple findings to make the review look thorough.
+- In PoC mode: do not demand answers the PoC owner cannot yet have. Frame open questions as "next step: team decision" or "add a story".

package/dist/cursor/.agents/skills/jahia-review-java/references/code-review-output.md

@@ -0,0 +1,121 @@
+# Skill: Code Review Output Format
+
+Load this skill before writing the review output. It defines the section order, finding template, and summary table schema.
+
+## When to load
+
+Always, just before writing the deliverable. Do not load during analysis passes.
+
+## Output mode selection
+
+Detect from context:
+
+| Signal | Mode |
+|---|---|
+| GitHub MCP tools available + a PR number in context | **PR mode**: inline comments + one summary comment |
+| Local filesystem only, module checked out, no PR | **File mode**: single markdown at repo root |
+| A prior `code-review-*.md` exists in the repo | **Follow-up mode**: see `skills/review-followup/SKILL.md` |
+
+When unclear, default to **File mode**.
+
+## File naming (File mode)
+
+`code-review-{module-name}-{YYYY-MM-DD}.md` at the module root. The module name comes from `pom.xml` `<artifactId>`.
+
+If a review already exists for the same date, append `-v2`, `-v3`, etc. Do not overwrite without explicit instruction.
+
+## Section order (mandatory)
+
+```
+# Code review — {module-name} (backend|frontend|fullstack)
+
+- Date: YYYY-MM-DD
+- Scope: {one line — what was reviewed, what was not}
+- Out of scope: {one line — explicit exclusions}
+
+{One short paragraph: overall posture. Lead with what is right; the findings list is for what is wrong. Do not pad.}
+
+## 1. Security
+## 2. API and backend design
+## 3. Bugs and rough edges
+## 4. Documentation and harness drift
+## 5. Build, Maven, and OSGi packaging
+## 6. OSGi and concurrency
+## 7. Tests
+## {N}. Prioritised summary
+## {N+1}. Closing note
+```
+
+Omit sections with no findings — write "No findings." inline only if the absence itself is worth noting (e.g. "No concurrency findings — all `@Component` services are stateless.").
+
+The Closing note is one paragraph. It names the single biggest risk and the single biggest strength. No bullet lists.
+
+## Finding template
+
+Each finding has the same shape:
+
+```markdown
+### {N.M} {Short title} — {severity emoji} P{0|1|2|3}
+
+{One sentence: the problem.}
+
+{2-6 sentences: why it matters, where it manifests, what triggers it. Code snippet if it clarifies in fewer words than prose.}
+
+**Fix:** {Concrete action. Library name + method, or class change, or "accept and document".}
+
+**Effort:** {XS | S | M | L}
+```
+
+Rules:
+
+- **Severity emoji + level** in the heading. Never one without the other.
+- **The problem in one sentence.** If you need a paragraph, you have not understood it yet.
+- **Code snippets are quoted, not paraphrased.** If the bug is in three lines of code, show those three lines.
+- **The Fix line is mandatory.** No exceptions. If there is no fix, the finding is "accept and document" — say so explicitly.
+- **Effort is mandatory.** Authors prioritise by effort × severity. Without effort, the table is half-useless.
+
+## Anchors
+
+Use `ClassName#methodName` as the anchor for code references. Line numbers go stale; method names survive refactors. When a finding spans multiple files, list them under "Affected sites" inline.
+
+## Severity rules
+
+See the parent `AGENTS.md` severity table. One reminder: **the prioritised summary table is your honesty check**. If P0 has more than 5 items, you have inflated severity. Re-evaluate.
+
+## Prioritised summary table
+
+The penultimate section. Schema:
+
+| Priority | Item | Effort |
+|---|---|---|
+| 🔴 P0 | {one-line description with §X.Y backref} | XS/S/M/L |
+| ... |
+
+Sort by priority, then by section number. P3 items can be grouped if numerous.
+
+The backref (`§X.Y`) is mandatory — the reader uses the table as an index into the full findings.
+
+## PR mode specifics
+
+When posting to a PR:
+
+- **Inline comments** for findings that point to a specific file/line span. Use the same finding template, condensed.
+- **One summary comment** at the PR level containing:
+  - The opening paragraph (overall posture).
+  - The prioritised summary table.
+  - Links to the inline comments via their permalinks.
+- **No giant markdown dump in the summary comment.** Inline comments carry the body of each finding.
+
+If a finding cannot be anchored to a line (e.g. "the module has no tests"), it goes only in the summary comment.
+
+## Follow-up mode handoff
+
+If a prior review exists, hand off to `skills/review-followup/SKILL.md`. Do not write a fresh review.
+
+## What not to do
+
+- Do not number findings across the whole document (e.g. "Finding 47"). Number within sections: §1.1, §1.2, §3.1.
+- Do not split a finding into a "problem" finding and a "fix" finding. One finding = one problem + its fix.
+- Do not write a "tl;dr" at the top. The opening paragraph is the tl;dr.
+- Do not include process meta-commentary in the output ("During Pass 2 I noticed..."). The doc is for the author, not a log of your work.
+- Do not write recommendations the author cannot act on alone. If a fix requires a product decision, name the decision; do not pretend it is purely technical.

package/dist/cursor/.cursor/rules/jahia.mdc

@@ -17,7 +17,9 @@ You are helping develop a **Jahia JavaScript Module** — a React-based template
 5. **Always verify before creating** — check that content types are deployed, site keys are correct, and area structures exist before attempting GraphQL mutations.
 6. **All props are optional at runtime** — even mandatory CND fields. Always guard against `undefined` in views.
 7. **Always include `-H "Origin: http://localhost:8080"` in every GraphQL curl** — omitting it returns `Permission denied` even with correct credentials.
-8. **Accessibility is mandatory** — every component must pass WCAG 2.1 AA. After building any component or completing a task, invoke `/jahia-dev-accessibility` to run an axe-core audit and fix all `critical` and `serious` violations before declaring work done.
+8. **Build accessible HTML from the start** — every view must use semantic HTML (`<main>`, `<header>`, `<nav>`, `<footer>`, `<section>`, `<article>`), include exactly one `<h1>` per page, use a strict heading hierarchy (h1 → h2 → h3), add `alt` text to every `<img>`, and use sufficient colour contrast (≥ 4.5:1 for body text). Baking this in during authoring is faster than a post-hoc audit.
+9. **Run one accessibility audit at the end** — after all components are built and content is published, invoke `/jahia-dev-accessibility` once to catch any remaining violations. Do not audit after every individual component; it wastes time on pages that are not yet complete.
+10. **Batch builds and deploys** — build all components together, then run `yarn build && yarn jahia-deploy` once rather than after each individual component. Deploy once before populating content.
 
 ## Skill Map