docs(claude): trim CLAUDE.md, extract deploy/bot/browser docs, add anti-patterns #11-14

[bpamiri]

Summary

CLAUDE.md was 1133 lines, with 10 of 17 listed reference subdirectories missing and several broken doc paths (config/services.cfm, docs/src/...). This PR reorders, dedups, and trims it to 714 lines (-37%) with all internal links now resolving.

Top-of-file restructured so high-leverage content lands in working memory first:

• Code Map — where framework / demo app / CLI live and how they relate
• Before-Done checklist — which test suite to run for which change type
• Cross-Engine Invariants — promoted from buried Docker / Browser-Testing locations
• Anti-Patterns extended Top 10 → Top 14, all new entries sourced from recent merged PRs:
  • New master #11 CFML reserved scopes shadow parameters (fix(cli): rename consoleExec url param so /models /routes /version /datasource work #2591)
  • imageTag edit: if height and/or width values are set to false, the attrib #12 Empty array in whereIn / whereNotIn (feat(web/blog,model): beyond findAll post + whereIn empty-array fix #2736)
  • Issue 784 #13 Comma-list config ≠ single-value HTTP header (fix(middleware): Cors no longer emits raw comma list as Access-Control-Allow-Origin #2725)
  • Created README file for the project. This is heavily based on the CFWhee #14 Strip CFML comments before source-scanning (fix(cli): wheels validate must strip CFML comments before checking extends #2595)

Extracted to .ai/wheels/ (loaded only when relevant):

• .ai/wheels/deploy.md (92 lines) — wheels deploy Kamal-port reference
• .ai/wheels/wheels-bot.md (34 lines) — bot architecture
• .ai/wheels/testing/browser-testing.md (68 lines) — browser DSL

Other dedups: t.timestamps() 3-column rule, mixed-argument-style rule, and the "WheelsTest only for new tests" reminder now each appear in one canonical location. Reference Docs list at bottom lists only verified-to-exist files.

Related Issue

N/A — internal Claude-tooling improvement, no tracked issue.

Type of Change

• Bug fix
• New feature
• Enhancement to existing feature
• Documentation update
• Refactoring

Feature Completeness Checklist

• DCO sign-off — commit carries Signed-off-by: (used git commit -s)
• Tests — N/A (documentation only; no code changed)
• Framework Docs — N/A (this is internal Claude tooling, not user-facing guides on guides.wheels.dev)
• AI Reference Docs — three new files added under .ai/wheels/
• CLAUDE.md — rewritten (this is the primary deliverable)
• CHANGELOG.md — N/A (internal Claude tooling, not user-visible)
• Test runner passes — N/A (no code changed)

Test Plan

• All 14 internal markdown links in CLAUDE.md resolve to existing files (verified by shell script that extracted every `](path)` and stat'd it)
• CLAUDE.md trimmed from 1133 → 714 lines (-37%); extracted files total 194 lines under `.ai/wheels/`
• All 4 new anti-patterns reference real merged PRs with verifiable wrong/right code examples drawn from those PRs' diffs
• Reviewers: confirm the Code Map and Before-Done checklist accurately reflect how you actually work in this repo — they're the highest-leverage pieces and worth a close read

Screenshots / Output

n/a

[skip-claude]

[wheels-bot]

Wheels Bot — Reviewer A

This PR trims CLAUDE.md from 1133 → 714 lines, adds a Code Map and Before-Done checklist, promotes cross-engine rules to a top-level section, adds four new anti-patterns (#11–14) sourced from real merged PRs (#2591, #2736, #2725, #2595), and extracts the deploy/bot/browser-testing sections into dedicated .ai/wheels/ files. The overall restructuring is well-designed: high-leverage content is front-loaded, every internal link was verified to resolve, and the Reference Docs section no longer points to non-existent directories. Verdict: comment — three minor content losses worth noting, no blockers.

Correctness

The SOFT_FAIL_DBS two-occurrence sync note was dropped without adding it to the workflow.

Old CLAUDE.md (line 688) contained:

`SOFT_FAIL_DBS` appears twice in `.github/workflows/compat-matrix.yml` — once in the
"Run test suites" step and once in the "Generate per-engine summary" step. Both must be
kept in sync since the steps don't share shell state.

The new CLAUDE.md condenses this to: "Oracle is soft-fail in CI (see SOFT_FAIL_DBS in .github/workflows/compat-matrix.yml)".

Verified: compat-matrix.yml has two hard-coded SOFT_FAIL_DBS="oracle" assignments (lines 293 and 488) with no comment about the sync requirement. An agent or contributor who adds a new soft-fail DB and only updates line 293 will get inconsistent behaviour: the first loop soft-fails while the second hard-gates. There is no surviving documentation of this constraint anywhere in the codebase.

Suggested fix — add a comment in compat-matrix.yml at line 293 (and 488):

# Update this AND the matching assignment ~195 lines below — the two steps don't share shell state
SOFT_FAIL_DBS="oracle"

If not touching the workflow in this PR, restore a one-liner in the new CLAUDE.md testing section: "Update SOFT_FAIL_DBS in both the 'run suites' step and the 'summary' step — they don't share shell state."

Conventions

Anti-pattern #7 (timestamps()): code example was removed.

Old CLAUDE.md showed:

// WRONG — duplicates
t.timestamps();
t.datetime(columnNames="createdAt");

// RIGHT
t.timestamps();  // creates createdAt, updatedAt, AND deletedAt (soft-delete)

New CLAUDE.md (lines 141–142) replaces this with prose only — no WRONG/RIGHT code block. The rule is accurate, but the visible wrong pattern (t.datetime(columnNames="createdAt")) no longer appears. An agent generating migration code scans code blocks before prose; without the example the mistake stays invisible until after the fact.

Old anti-pattern #8 (Database-Agnostic Dates) lost its WRONG example.

Old CLAUDE.md had a dedicated ### 8. Database-Agnostic Dates in Migrations with:

// WRONG — database-specific
execute("INSERT INTO users (name, createdAt) VALUES ('Admin', CURRENT_TIMESTAMP)");

New CLAUDE.md merges this into anti-pattern #5 as a trailing // RIGHT comment only — CURRENT_TIMESTAMP is never shown as the wrong answer. An agent writing a migration that uses CURRENT_TIMESTAMP will not find a code-level warning. Suggest adding // WRONG — CURRENT_TIMESTAMP is database-specific as a preceding line, or restore the standalone heading.

Anti-pattern #3 (nested routes): flat separate declarations option was silently removed.

Old CLAUDE.md included a third valid form:

// RIGHT — flat separate declarations (no URL nesting)
.resources("posts")
.resources("comments")

New CLAUDE.md drops this. The flat form is the right answer when URL nesting isn't needed, and its absence may push agents toward the callback form unnecessarily.

Docs

All 17 internal links in new CLAUDE.md were verified to resolve to existing files/directories. The Reference Docs section now correctly lists only what exists — the old version pointed to 10+ non-existent directories (.ai/wheels/models/, .ai/wheels/database/, .ai/wheels/configuration/, etc.), so this is a meaningful improvement.

The three helper function paths cited in anti-pattern #14 (cli/lucli/services/Analysis.cfc, cli/lucli/Module.cfc, cli/lucli/services/Doctor.cfc) all verified to exist.

Relative ../../docs/ links in .ai/wheels/deploy.md were verified to resolve from the repo root.

Commits

One commit: docs(claude): trim CLAUDE.md, extract deploy/bot/browser docs, add anti-patterns #11-14

• Type docs ✓ — scope claude ✓ (unrestricted) — subject 75 chars, not ALL-CAPS ✓
• DCO sign-off present (Signed-off-by: Peter Amiri <peter@alurium.com>) ✓
• Targets develop ✓

[wheels-bot]

Wheels Bot — Reviewer B (round 1)

A's review is thorough and largely accurate: the three content-loss findings are real and well-evidenced. However, A missed one factual error introduced by the extraction into .ai/wheels/wheels-bot.md that should be flagged. Not aligned.

Sycophancy

None detected. A issued a comment verdict (not approve) and substantiated each finding with diff line references.

False positives

None detected. I verified A's four claims against the diff:

• SOFT_FAIL_DBS two-occurrence note dropped: confirmed. Old CLAUDE.md contained the explicit "both must be kept in sync" instruction; new file condenses to a single reference pointer with no sync note.
• timestamps() WRONG/RIGHT code block removed: confirmed. The t.datetime(columnNames="createdAt") counter-example is gone; only prose survives.
• Database-Agnostic Dates standalone section removed: confirmed. Old anti-pattern adding better description for hasManyCheckBox #8 with CURRENT_TIMESTAMP as the WRONG case is absent; only the // RIGHT — and use NOW() trailing comment in anti-pattern New master - Microsoft Access Adapter #5 remains.
• Flat-separate-declarations form dropped from anti-pattern New master #3: confirmed. .resources("posts") / .resources("comments") no longer appears.

Missed issues

.ai/wheels/wheels-bot.md states an incorrect loop cap for Reviewer B.

.ai/wheels/wheels-bot.md line 11 (the Stages table):

| Reviewer B | … | Loop cap = 3 rounds. |

The actual cap is 10 rounds per SHA, as stated consistently across:

• .claude/commands/review-the-review.md ("Loop cap: 10 rounds per SHA")
• .claude/commands/advise-on-deadlock.md ("Reviewer A and Reviewer B reached the 10-round inner-loop cap")
• .claude/commands/respond-to-critique.md ("Loop cap is enforced by Reviewer B (10 rounds max per SHA)")
• .github/workflows/bot-advisor.yml (fires on the inner-loop cap B emits at round 10)

The error was pre-existing in old CLAUDE.md and was faithfully carried into the new extracted file. The extraction is an opportunity to correct it. Any agent consulting .ai/wheels/wheels-bot.md will believe the loop terminates far sooner than it does, which could cause incorrect reasoning about convergence state.

Fix: change "Loop cap = 3 rounds" to "Loop cap = 10 rounds per SHA" in the Stages table.

Verdict alignment

A's comment verdict is consistent with the findings (three minor documentation-quality concerns, no blockers). The missed loop-cap error also warrants only a comment-level correction, not a blocker.

Convergence

Not aligned. A needs to verify the Reviewer B loop cap value in .ai/wheels/wheels-bot.md and flag it as a correction needed (or confirm the discrepancy is intentional, which it is not). Once A addresses this — either by flagging the correction or conceding it — we are aligned on a comment verdict with one additional fix needed.

[wheels-bot]

Wheels Bot — Reviewer A response (round 1)

B confirmed all four of my original findings as valid and raised one missed issue: the Reviewer B loop cap in the newly extracted .ai/wheels/wheels-bot.md is documented as 3 rounds when every authoritative source in the repo says 10. I concede that finding; it is clearly wrong and I should have caught it. No other adjustments needed. Verdict stays at comment.

Conceded points

• Loop cap error in .ai/wheels/wheels-bot.md: The Stages table in the extracted file reads Loop cap = 3 rounds for Reviewer B. Verified against the diff and cross-checked with .claude/commands/review-the-review.md ("Loop cap: 10 rounds per SHA"), .claude/commands/advise-on-deadlock.md ("10-round inner-loop cap"), .claude/commands/respond-to-critique.md ("10 rounds max per SHA"), and .github/workflows/bot-advisor.yml header comment. All four say 10. The extraction faithfully copied a pre-existing error from old CLAUDE.md rather than correcting it. The fix is a one-word change in the table cell: Loop cap = 3 rounds → Loop cap = 10 rounds per SHA. This should be flagged as a required correction alongside the four content-loss items from my initial review.

Defended points

• All four original findings stand (B confirmed them, no rebuttal needed):
  • SOFT_FAIL_DBS sync note dropped — two hard-coded assignments in compat-matrix.yml (lines 293 and 488) have no surviving documentation of their must-stay-in-sync constraint.
  • Anti-pattern #7 code block removed — the t.datetime(columnNames="createdAt") counter-example is gone; prose only survives.
  • Anti-pattern #8 WRONG example removed — CURRENT_TIMESTAMP no longer appears as the wrong answer; only a trailing // RIGHT comment in anti-pattern #5 remains.
  • Anti-pattern #3 flat form dropped — the flat separate-declarations form (.resources("posts") / .resources("comments")) has been silently removed.

Updated verdict

Still comment — five documentation-quality items (four content losses plus the loop cap correction), none of which are blocking defects, but all of which degrade the accuracy of the extracted docs for both humans and agents.