@jahia/agentic 0.1.1 → 0.3.0

package/dist/copilot/.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/copilot/.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/copilot/.agents/skills/jahia-jcr-sql2/SKILL.md

@@ -0,0 +1,258 @@
+---
+name: jahia-jcr-sql2
+description: JCR-SQL2 reference for Jahia queries. Use when building, reviewing, or debugging SQL2 statements for content listings, full-text search, sorting, pagination, or Java back-end query code.
+---
+
+# Skill: jahia-jcr-sql2
+
+Use this skill when you need the JCR-SQL2 language itself: selectors, path constraints, filters, ordering, full-text syntax, joins, pagination rules, and performance guardrails.
+
+---
+
+## When to use JCR-SQL2
+
+JCR-SQL2 is the standard Jahia query language for:
+
+- listing pages or content with filtering and sorting
+- querying a folder subtree
+- searching by property value, date, or reference
+- full-text search across indexed content
+- back-end Java code using `QueryManagerWrapper`
+- template-set listings that use `useJCRQuery` or the Page Builder query component
+
+---
+
+## Basic syntax
+
+### Select by node type
+
+```sql
+SELECT * FROM [jnt:page] AS page
+SELECT * FROM [jnt:content] AS content
+SELECT * FROM [jnt:file] AS file
+```
+
+The selector matches the named type and its subtypes.
+
+### Common node types
+
+| Type | Meaning |
+|------|---------|
+| `jnt:page` | pages |
+| `jnt:content` | editorial content |
+| `jnt:file` | files |
+| `jnt:virtualsite` | sites |
+| `jmix:searchable` | general searchable content |
+| `nt:base` | all nodes — avoid unless paired with a strict path |
+
+---
+
+## Path constraints
+
+### Recursive subtree
+
+```sql
+SELECT * FROM [jnt:page] AS page
+WHERE ISDESCENDANTNODE(page, '/sites/luxe/home')
+```
+
+### Direct children only
+
+```sql
+SELECT * FROM [jnt:page] AS page
+WHERE ISCHILDNODE(page, '/sites/luxe/home')
+```
+
+**Guardrail:** always constrain by path to avoid repository-wide scans.
+
+---
+
+## Property constraints
+
+### Exact match
+
+```sql
+WHERE page.[j:templateName] = 'home'
+WHERE node.[jcr:title] = 'My Title'
+```
+
+### Pattern match
+
+```sql
+WHERE node.[jcr:title] LIKE '%keyword%'
+WHERE node.[j:nodename] LIKE '%.png'
+```
+
+### Null checks
+
+```sql
+WHERE page.[jcr:title] IS NOT NULL
+```
+
+### Boolean
+
+```sql
+WHERE node.[j:published] = CAST('true' AS BOOLEAN)
+```
+
+### Date comparison
+
+```sql
+WHERE page.[jcr:lastModified] > CAST('2026-01-01T00:00:00.000Z' AS DATE)
+```
+
+Use the millisecond form `yyyy-MM-dd'T'HH:mm:ss.SSSX` for SQL2 date casts.
+
+### Multiple conditions
+
+```sql
+WHERE ISDESCENDANTNODE(page, '/sites/luxe')
+  AND page.[jcr:lastModified] > CAST('2026-01-01T00:00:00.000Z' AS DATE)
+```
+
+### OR conditions
+
+```sql
+WHERE node.[jcr:primaryType] = 'jnt:bigText'
+   OR node.[jcr:primaryType] = 'jnt:article'
+```
+
+---
+
+## Ordering
+
+```sql
+ORDER BY page.[jcr:lastModified] DESC
+ORDER BY page.[jcr:created] ASC
+ORDER BY node.[jcr:title]
+```
+
+Multiple columns:
+
+```sql
+ORDER BY page.[j:templateName] ASC, page.[jcr:lastModified] DESC
+```
+
+---
+
+## Full-text search
+
+### Search indexed content
+
+```sql
+WHERE CONTAINS(node.*, 'digital')
+```
+
+### Search one property
+
+```sql
+WHERE CONTAINS(node.[jcr:title], 'welcome')
+```
+
+### Expression syntax
+
+| Syntax | Meaning |
+|--------|---------|
+| `term` | must contain the term |
+| `term1 term2` | implicit AND |
+| `term1 OR term2` | either term |
+| `"exact phrase"` | exact phrase |
+| `-term` | exclude term |
+
+### Relevance sort
+
+```sql
+SELECT * FROM [jnt:content] AS n
+WHERE ISDESCENDANTNODE(n, '/sites/luxe')
+  AND CONTAINS(n.*, 'digital')
+ORDER BY SCORE(n) DESC
+```
+
+Combine full-text with path constraints for performance.
+
+---
+
+## Joins
+
+```sql
+SELECT * FROM [jnt:imageReferenceLink] AS img
+INNER JOIN [jnt:file] AS file
+ON img.[j:node] = file.[jcr:uuid]
+WHERE img.[j:node] = 'UUID'
+```
+
+Jahia supports inner joins, but keep them focused and path-constrained whenever possible.
+
+---
+
+## Using SQL2 in Jahia code
+
+### Template-set listing with `useJCRQuery`
+
+```tsx
+const posts = useJCRQuery({
+  query: `SELECT * FROM [namespace:blogPost] AS post
+          WHERE ISDESCENDANTNODE(post, '/sites/${siteKey}/contents/blog')
+          ORDER BY post.[publicationDate] DESC`,
+});
+```
+
+### Java back-end query execution
+
+```java
+QueryManagerWrapper qm = session.getWorkspace().getQueryManager();
+QueryWrapper query = qm.createQuery(sql2Statement, Query.JCR_SQL2);
+query.setLimit(limit);
+query.setOffset(offset);
+JCRNodeIteratorWrapper nodes = query.execute().getNodes();
+```
+
+**Guardrail:** never embed `LIMIT` or `OFFSET` inside the SQL2 string. Use `setLimit()` and `setOffset()`.
+
+---
+
+## Security and validation
+
+### Escape user input
+
+In Java back-end code, escape user-provided values with `JCRContentUtils.sqlEncode()` before interpolating them into a SQL2 string.
+
+```java
+String safeValue = JCRContentUtils.sqlEncode(userInput);
+```
+
+### Validate dynamic sort fields
+
+If a user can choose the sort field, validate it against a whitelist before interpolating it into `ORDER BY`.
+
+---
+
+## Performance best practices
+
+1. Always constrain by path.
+2. Use the most specific node type possible.
+3. Keep result sets small.
+4. Prefer indexed equality filters over broad `LIKE '%...%'` patterns.
+5. Use full-text sparingly on large trees.
+6. Sort on common indexed fields such as `jcr:lastModified` or `jcr:created`.
+7. Cap API result limits to a sane maximum.
+
+---
+
+## Quick checklist
+
+- [ ] Query has a path constraint
+- [ ] Node type is specific
+- [ ] Sort field is intentional and safe
+- [ ] Full-text is combined with a subtree path
+- [ ] Dates use `yyyy-MM-dd'T'HH:mm:ss.SSSX`
+- [ ] Java code uses `setLimit()` and `setOffset()` instead of inline SQL clauses
+
+---
+
+## Related skills
+
+- `/jahia-dev-query-content` — apply SQL2 inside Page Builder queries and JS module views
+- `/jahia-dev-define-content-type` — define the content types you will query
+- `/jahia-java-jcr` — implement back-end JCR logic around the query
+

package/dist/copilot/.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".