[EPIC] Backend AI-Context Rock #37124

Description

Our backend AI context is inconsistent and partially unreachable, so AI-generated code repeats the same mistakes and burns code-review cycles on known issues. Concrete example: new integration tests are generated but never registered in a MainSuite — the rule exists in docs/testing/INTEGRATION_TESTS.md, but it's absent from root CLAUDE.md's Critical Rules and a slash command even contradicts it. AI-assisted code review is similarly inconsistent because its input context is poor: 11 backend docs are orphaned (unlinked from any index, so on-demand loading never reaches them), and live contradictions exist (e.g., CLAUDE.md says Java 25 while JAVA_STANDARDS.md still says Java 11/21).

Scope note: This quarter we fix and consolidate what exists. Writing new subsystem context (content lifecycle, upgrade tasks, caching, workflow, etc.) is explicitly deferred — this Rock produces the documented backlog so next quarter starts execution-ready.

Ownership split

Fabrizzio's milestones are tracked in his own sub-issues, listed below alongside Jose's.

Milestone schedule

⚠️ Deadline risk — decision still open, now overdue. At the corrected Aug 18 start the natural sign-off lands Oct 19 — 7 days past the fixed Oct 12 deadline. The decision was due before M0 started; Falcon's M0–M3 have since merged without it being taken.

It now binds harder on the Scout half, whose milestones start Sep 16. The monitoring gates this Rock requires — 1–2 weeks per merged change — do not fit in the remaining window: an M1 merged Sep 24 has its gate close after the deadline. Either the gate standard is relaxed for Scout's changes (and condition 2 of the Definition of Done is met on weaker evidence than the backend half got), or the Oct 12 date moves. Needs an explicit call.

Jose's sub-issues (Falcon)

• M0 — Backend context audit #37125 — M0 — Backend context audit (complete)
• M1 — Fix backend contradictions #37126 — M1 — Fix backend contradictions
• M2 — Link orphaned backend docs #37127 — M2 — Link orphaned backend docs
• M3 — Consolidate backend duplicates #37128 — M3 — Consolidate backend duplicates
• M4 — Backend gap backlog #37129 — M4 — Backend gap backlog

Fabrizzio's sub-issues (Scout)

• M0 — Scout context audit (testing, core slice, rules, commands) #37576 — M0 — Scout context audit (docs/testing/, docs/core/ slice, .cursor/rules/, .claude/commands/)
• M1 — Fix Scout contradictions #37577 — M1 — Fix Scout contradictions
• M2 — Link orphaned Scout docs & rebuild docs/README.md as a complete index #37578 — M2 — Link orphaned Scout docs & rebuild docs/README.md as a complete index
• M3 — Consolidate Scout duplicates #37579 — M3 — Consolidate Scout duplicates
• M4 — Testing & tooling gap backlog #37580 — M4 — Testing & tooling gap backlog
• Quality gate — integration-test registration failure mode #37581 — Quality gate — integration-test registration failure mode

Two of these were not in the original milestone plan, and are called out because the Definition of Done depends on them:

• M2 — Link orphaned Scout docs & rebuild docs/README.md as a complete index #37578 also rebuilds docs/README.md and commits an automated reachability check. M2 on the backend side linked orphans into CLAUDE.md's navigation, but docs/README.md — the other index this Rock's scope names — still carries 11 links, 10 of them frontend. The automated check is what makes "every doc reachable" verifiable on every PR instead of a one-time sweep.
• Quality gate — integration-test registration failure mode #37581 runs the monitoring gate on integration-test registration, the concrete failure mode in this epic's own problem statement. The fix merged across M2 — Link orphaned backend docs #37127 and M3 — Consolidate backend duplicates #37128 (Falcon), but docs/testing/INTEGRATION_TESTS.md sits in Scout's slice, so no one currently owns the 1–2 weeks of watching real PRs that condition 2 requires.

Baseline measured on main at dfbe40f (Sep 16): 52 .md files under docs/, 45 reachable from a root index, 7 orphaned. docs/backend/ and docs/infrastructure/ are clean — #37127 closed those. Of the 7 remaining, 4 sit in directories owned by neither team (docs/cli/, docs/claude/, docs/test-cases/) — the same ownership gap this Rock already hit with docs/integration/ and resolved in #37129.

Desired Outcome

This Rock lands when all three Definition-of-Done conditions are true (binary — all three must hold):

1. All consolidation fixes (M1–M3) merged to main.
2. Quality gate passed — each merged context change monitored by its responsible dev against real daily PRs / AI-review output for roughly 1–2 weeks, and the targeted failure mode confirmed stopped recurring (not just "no one touched it").
3. Gap backlog published and reviewed with the team — ready to become next quarter's Rock.

Initial failure-mode watch list (finalized in M0):

• Integration tests created without MainSuite / Junit5Suite registration
• Wrong Java-version idioms suggested by AI
• AI guidance citing docs that contradict each other or don't exist
• AI review missing dotCMS-specific checks because the relevant doc was unreachable

Two of the failure modes below are confirmed still live, in .cursor/rules/ — the one area no milestone has audited yet (found Sep 16 while scoping #37577):

• The Java-version mismatch survives. .cursor/rules/java-context.mdc still states Core: Java 11 syntax. CLI: Java 21 ok. Runtime: Java 21. Root CLAUDE.md:68 no longer pins a version — it defers to .sdkmanrc and dotcms.core.compiler.release in parent/pom.xml. M1 (M1 — Fix backend contradictions #37126) fixed the docs, but the Cursor rule sat outside Falcon's slice and was left behind. The problem statement's second failure mode is still being served to anyone working from Cursor.
• The integration-test registration rule never reached Cursor. MainSuite/Junit5Suite appears nowhere under .cursor/rules/. test-context.mdc gives a command for running integration tests with no mention that an unregistered test compiles, passes, and is silently never run in CI — the rule M2 — Link orphaned backend docs #37127 added to CLAUDE.md's Critical Rules. This is the epic's opening example, unfixed in one of its two entry points.

Both land in #37577; the second also feeds the gate in #37581. They are the practical argument for the scope of #37576: .cursor/rules/ and .claude/commands/ are 14 files that no milestone in M0–M3 read, and the two checked so far both carry stale guidance.

Target Personas

• Developer teams
• Content teams
• DevOps teams
• System administrators (dotCMS)

Links

• Milestone roadmap (Gantt chart)