M0 — Backend context audit #37125

Activity

1. jcastro-dotcms

   added

   Type : Documentation

   dotCMS : Technical DebtDealing with long standing tech debtDealing with long standing tech debt

   Team : Falcon

   on Aug 20, 2026
2. github-project-automation

   added this to dotCMS - Product Planningon Aug 20, 2026
3. github-project-automation

   moved this to New in dotCMS - Product Planningon Aug 20, 2026
4. jcastro-dotcms

   added the

   Task

   issue type on Aug 20, 2026
5. jcastro-dotcms

   added a parent issue on Aug 20, 2026

   • [EPIC] Backend AI-Context Rock #37124
6. jcastro-dotcms

   self-assigned this

   on Aug 20, 2026
7. jcastro-dotcms commented on Aug 20, 2026

   

   jcastro-dotcms

   on Aug 20, 2026

   MemberAuthor

   More actions

   M0 Audit — Findings

   All acceptance criteria above are met — status: complete.

   Originally expected (from initial scoping)

   Contradictions (1 expected)

   • Java version — CLAUDE.md says 25, docs/backend/JAVA_STANDARDS.md:4-6 says 21 (runtime) / 11 (syntax)

   Duplication (3 expected)

   • docs/backend/JAVA_STANDARDS_FOCUSED.md → fold into JAVA_STANDARDS.md
   • docs/backend/REST_API_PATTERNS_FOCUSED.md → fold into REST_API_PATTERNS.md
   • Four-doc OpenSearch cluster (OPENSEARCH_MIGRATION.md, OPENSEARCH_MIGRATION_TEST_PLAN.md, OPENSEARCH_CLIENT_CONFIGURATION.md, OPENSEARCH_MIGRATION_TESTER_GUIDE.md) — assumed duplicative

   Orphaned files (12 expected)
   docs/backend/SECURITY_BACKEND.md, OPENSEARCH_MIGRATION.md, JAVA_STANDARDS_FOCUSED.md, REST_API_PATTERNS_FOCUSED.md, SEARCH_API_MIGRATION.md, OPENSEARCH_MIGRATION_TEST_PLAN.md, TELEMETRY_IMPLEMENTATION.md, OPENSEARCH_CLIENT_CONFIGURATION.md, OPENSEARCH_MIGRATION_TESTER_GUIDE.md, JANDEX_METADATA_SCANNING.md; docs/core/CODE_STRUCTURE.md; docs/infrastructure/CI_COMPONENTS_DTS_FIX.md

   ---

   Found during this audit (beyond initial scope)

   Additional contradictions (5 found)

   1. Java version is also wrong in docs/core/ARCHITECTURE_OVERVIEW.md:6, docs/core/CODE_STRUCTURE.md:10,12, and docs/infrastructure/DOCKER_BUILD_PROCESS.md:830 — all three already linked from CLAUDE.md, so this isn't just an orphan problem. 5 files need this fix, not 1-2.
   2. Angular version wrong in docs/core/ARCHITECTURE_OVERVIEW.md:7 and docs/core/CODE_STRUCTURE.md:11,145 (says 18.2.3; core-web/package.json:57 says 22.1.0) — frontend content in Jose's files, flagged to Fabrizzio.
   3. Fictional API: docs/backend/REST_API_PATTERNS.md:292 (linked) and docs/backend/SECURITY_BACKEND.md:138,152,171 call permissionAPI.hasPermission(...) / securityAPI.hasPermission(...) — no such method exists on PermissionAPI (verified against PermissionAPI.java). Correct method: doesUserHavePermission(...).
   4. Self-contradicting property-naming rule: docs/backend/CONFIGURATION_PATTERNS.md:112-119 flags uppercase properties as a "❌ Wrong" anti-pattern, but its own :87-88 example, plus OPENSEARCH_CLIENT_CONFIGURATION.md and OPENSEARCH_MIGRATION.md, all correctly use uppercase.
   5. docs/backend/JAVA_STANDARDS.md:250 recommends a build command CLAUDE.md:33 explicitly flags as unreliable (minor).

   Corrections to initial assumptions

   • Four-doc OpenSearch cluster is duplicative — ruled out. Read all four; well-organized and cross-referenced, not overlapping. This is a link fix (M2), not a dedupe fix (M3).
   • SECURITY_BACKEND.md duplicates docs/core/SECURITY_PRINCIPLES.md — ruled out, checked as a candidate. SECURITY_PRINCIPLES.md:78 explicitly delegates to SECURITY_BACKEND.md; complementary, not duplicate.

   Additional duplication found (1)

   • docs/core/CODE_STRUCTURE.md (orphaned, 216 lines) substantially duplicates docs/core/ARCHITECTURE_OVERVIEW.md (linked, 45 lines) — and the orphan is the more complete file. Needs a consolidation decision, not just a link.

   Nuance on the two known _FOCUSED duplicates

   • Neither is a clean subset — each has unique content that must be folded into its parent before deletion: JAVA_STANDARDS_FOCUSED.md has a Build Requirements section, an integration-test example, and package-location info not in JAVA_STANDARDS.md. REST_API_PATTERNS_FOCUSED.md has URL-versioning rules and a required-annotations reference not in REST_API_PATTERNS.md — and holds the correct permission-check example that needs to survive the merge.

   Cross-boundary coordination (touches Fabrizzio's scope)

   • docs/core/PROGRESSIVE_ENHANCEMENT.md (Fabrizzio's file) duplicates CLAUDE.md:81-87's own Progressive Enhancement section (Jose's file) — section mixes Java and Angular examples, needs a joint fix.
   • Angular-version contradiction above — heads-up only, fix stays in Jose's files.

   Out-of-scope discovery — flagged for the M4 backlog

   • docs/integration/API_CONTRACTS.md exists and is referenced by docs/core/SECURITY_PRINCIPLES.md:80, but the whole docs/integration/ directory is unlinked from CLAUDE.md and unowned by either Jose or Fabrizzio in the current split.
8. jcastro-dotcms commented on Aug 20, 2026

   

   jcastro-dotcms

   on Aug 20, 2026

   MemberAuthor

   More actions

   Follow-up — independent re-audit

   Ran a second, fully independent pass (fresh context, no knowledge of the findings above) to double-check completeness before treating M0 as closed. It reconfirmed everything in the comment above — the OpenSearch-cluster-isn't-duplicative call, the SECURITY_BACKEND/SECURITY_PRINCIPLES non-duplication, both _FOCUSED duplicates, all 12 orphans — but it also turned up real issues the first pass missed. Folded into M1's acceptance criteria (#37126); recording the evidence here.

   docs/backend/HEALTH_MONITORING.md — fabricated API (this file is linked/authoritative, not orphaned).
   HealthCheckLocator.registerHealthCheck(...) / .getAllHealthChecks() (lines ~69-82, 229, 251) don't exist anywhere in the codebase. Real mechanism: CDI auto-discovery via HealthCheckRegistry injecting Instance<HealthCheck>, with providers implementing HealthCheckProvider.getHealthChecks(). Also, HealthStatus.HEALTHY / HealthStatus.UNHEALTHY (lines 42, 48, 56, 163, 170, 197, 205, 213, 260) aren't real enum values — the actual HealthStatus enum is UP / DEGRADED / DOWN / UNKNOWN.

   docs/backend/SECURITY_BACKEND.md — a second, separate fabrication beyond the permission-API bug already found.
   Line 255: import org.springframework.web.util.HtmlUtils — zero Spring dependencies exist anywhere in this codebase (verified: no org.springframework imports, no Spring artifacts in any pom.xml). Real HTML-escaping utilities in use: OwaspEncoderTool or Xss.

   docs/infrastructure/DOCKER_BUILD_PROCESS.md — more broken than the Java-version line alone suggested.

   • Wrong docker-maven-plugin version: doc says 0.43.4, parent/pom.xml sets 0.48.0
   • Fabricated apt-get install -y openjdk-11-jre-headless step (~line 193) — real Dockerfile installs Java via SDKMAN (SDKMAN_JAVA_VERSION="25.0.2-ms")
   • Fabricated Dockerfile stage names/ARGs (~lines 174-207) — real file uses a container-base stage and SDKMAN_JAVA_VERSION ARG; java.base.image.version doesn't exist
   • Self-contradiction: debug port given as both 5005 (~line 203) and 8000 (~lines 807-814) in the same doc — actual port is 8000
   • Fabricated standalone ./dev-run script with --debug --glowroot flags (~lines 577-584) — only the justfile's dev-run target exists

   docs/backend/OPENSEARCH_MIGRATION_TEST_PLAN.md / OPENSEARCH_MIGRATION_TESTER_GUIDE.md — broken setup paths.
   Both reference docker/docker-compose-examples/os-migration/ (7 occurrences total) — the real path is docker/docker-compose-examples/single-node-os-migration/. Also reference a docker-compose.limited-user.yml that doesn't exist. A tester following these instructions literally can't bring up the lab environment. (These two docs are still correctly not duplicative of each other — that finding holds.)

   Minor

   • docs/backend/JAVA_STANDARDS.md:136 — broken anchor link to REST_API_PATTERNS.md#view-object-pattern-valueimmutable; the real header slug is #view-object-pattern-java-records
   • docs/backend/REST_API_PATTERNS_FOCUSED.md:101 — fabricated SecurityUtils.sanitizeInput(...); neither real SecurityUtils class has this method
   • Low confidence: docs/backend/JAVA_STANDARDS.md's "CLI Tools Exception: Java 21 features allowed in tools/dotcms-cli only" is backwards — tools/dotcms-cli/pom.xml:27-28 actually pins the CLI to maven.compiler.release=11, the most conservative target in the repo

   Not re-opening, but worth noting: docs/core/PROGRESSIVE_ENHANCEMENT.md is outside this ticket's 4-file docs/core/ scope, so its content wasn't re-audited — but the independent pass confirmed CLAUDE.md has its own inline "Progressive Enhancement" section (lines 81-87) covering similar ground, which is the same cross-boundary item already flagged above for coordination with Fabrizzio.

   Updated M1 (#37126) acceptance criteria to cover all of the above.
9. jcastro-dotcms

   moved this from New to Done in dotCMS - Product Planningon Aug 20, 2026
10. jcastro-dotcms

    closed this as completedby moving to Done in dotCMS - Product Planningon Aug 20, 2026
11. jcastro-dotcms

    linked a pull request that will close this issuefix(docs): correct contradictions and fabricated APIs in backend AI-context docs #37258on Sep 24, 2026