docs: Document Bundler frozen-mode lockfile mismatch (WA-DOC-010)

[kitcommerce]

Summary

Adds canonical documentation for the recurring CI failure:

The gemspecs for path gems changed, but the lockfile can't be updated because frozen mode is set.

This error has blocked multiple PRs (#865, #866). This PR makes the fix easy to discover and follow.

Changes

• docs/source/articles/bundler-frozen-mode-lockfile-fix.html.md (new)

  • Exact CI error string (grep-able)
  • Step-by-step fix using rbenv local 3.2.7 + bundle install + commit
  • Common gotchas: wrong Ruby version, vendor/bundle interference, wrong base branch
  • Explanation of why frozen mode is used in CI
  • Links back to related issues (Add Docker Compose env var check script #865, Improve Rails compatibility CI messaging for experimental failures #866, WA-DOC-010: Document Bundler frozen-mode lockfile mismatch (canonical fix steps) #877)

• CONTRIBUTING.md (updated)

  • New section with a quick-fix snippet and link to the full article
  • First place contributors look when a CI check fails → now surfaces the fix immediately

Verification

grep -r "gemspecs for path gems" --include="*.md" -l
# → docs/source/articles/bundler-frozen-mode-lockfile-fix.html.md
# → CONTRIBUTING.md

grep -r "frozen mode" --include="*.md" -l
# → both files

Closes #877

[kitcommerce]

Wave 1 Review — ✅ APPROVE

PR: docs: Document Bundler frozen-mode lockfile mismatch (WA-DOC-010)

---

Architecture ✅

• CONTRIBUTING.md is exactly the right anchor — first place contributors look on CI failure.
• docs/source/articles/ is the established location for long-form articles; placement is consistent with existing docs.
• Two-tier structure (quick-fix snippet in CONTRIBUTING.md → full article via link) is clean and appropriate.

Simplicity ✅

• CONTRIBUTING addition is lean (~30 lines), covers only what a contributor needs in the moment.
• 126-line article is appropriately thorough without being padded — gotchas table, rebase path, and "why frozen mode?" section are all genuinely useful.

Security ✅

• Documentation only. All shell snippets (rbenv local, bundle install, git add/commit/push) are standard, safe, and non-destructive.

Rails/Workarea Conventions ✅

• Front-matter format (title, created_at, excerpt) matches the existing article template.
• Commit message prefix (docs:) is consistent with project conventions.
• Minor non-blocking nit: the suggested commit message in the quick-fix snippet uses docs: regenerate Gemfile.lock — semantically a chore: would be slightly more accurate, but this is cosmetic and not worth a change request.

---

All four Wave 1 checks pass. Acceptance criteria fully met: canonical fix steps documented ✅, common gotchas covered ✅, linked from CONTRIBUTING.md ✅.

[kitcommerce]

Wave 2 Review — Database

Verdict: PASS

No database concerns — pure documentation change (CONTRIBUTING.md only). No schema changes, no queries, no migrations.

{"reviewer": "database", "pr": 1006, "wave": 2, "verdict": "PASS", "findings": [], "summary": "Pure documentation change — no schema, queries, or migrations affected."}

[kitcommerce]

🔒 Rails-Security Review — Wave 2

{
  "reviewer": "rails-security",
  "pr": 1006,
  "wave": 2,
  "verdict": "PASS",
  "findings": [
    {"severity": "INFO", "description": "Docs-only change. Documented commands (rbenv local, bundle install, git add/commit/push) are standard safe developer workflow. No code or dependency changes. CI frozen mode is itself a security-positive pattern.", "location": "CONTRIBUTING.md"}
  ],
  "summary": "No security concerns — pure documentation of existing CI troubleshooting steps."
}

Details: This PR adds troubleshooting documentation to CONTRIBUTING.md for a common CI failure. No code, no dependency changes, no Gemfile modifications. The documented workflow is standard and the advice to pin Ruby 3.2.7 for lockfile regeneration ensures consistency. The existing --frozen CI flag remains a security-positive control against supply chain drift.

✅ PASS — no security issues found.

[kitcommerce]

Wave 2 Review — Test Quality

Verdict: PASS

Documentation-only change. No test coverage required.

[kitcommerce]

Wave 3 — Performance / Frontend / Accessibility

Verdict: N/A (bypassed)

Documentation-only change. No performance, frontend, or accessibility review required.

Wave 3 complete. PR is ready for merge.