chore: add Serena project memories#31
Conversation
Persist Serena MCP project memory files (.serena/memories/) so they travel with the repo. Future sessions, fresh checkouts, and worktrees activate the project with full onboarding context (overview, structure, suggested commands, code style, task completion checklist) without re-running onboarding. Also add .worktrees/ to .gitignore for project-local git worktree usage. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
Warning Rate limit exceeded
To keep reviews running without waiting, you can enable usage-based add-on for your organization. This allows additional reviews beyond the hourly cap. Account admins can enable it under billing. ⌛ How to resolve this issue?After the wait time has elapsed, a review can be triggered using the We recommend that you space out your commits to avoid hitting the rate limit. 🚦 How do rate limits work?CodeRabbit enforces hourly rate limits for each developer per organization. Our paid plans have higher rate limits than the trial, open-source and free plans. In all cases, we re-allow further reviews after a brief timeout. Please see our FAQ for further information. ℹ️ Review info⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (4)
WalkthroughThis PR adds five memory documentation files to Changes
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~3 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
.serena/memories/project_overview.md (1)
1-45:⚠️ Potential issue | 🟡 MinorAddress markdownlint-cli2 failures (blank lines around headings/fences).
Static analysis hints for this file indicate
markdownlint-cli2issues like:
- MD022 “Headings should be surrounded by blank lines”
- MD031 “Fenced code blocks should be surrounded by blank lines”
Even though these are “docs-only”, they can still fail CI if markdown lint is enforced (and your PR objective mentions “CI green”). Please run
composer lint:md/composer lint:md:fix(or the repo’s markdownlint workflow) and apply the autofix results.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.serena/memories/project_overview.md around lines 1 - 45, The markdown file violates markdownlint rules MD022/MD031 — add blank lines above and below each heading (e.g., "UnitTestInterface — Project Overview", "Testing capabilities", "Tech Stack", etc.) and ensure fenced sections (any triple-backtick/code-like blocks or lists that act as fences) are surrounded by blank lines; then run the repository lint autofix (composer lint:md or composer lint:md:fix) and commit the resulting changes so CI passes..serena/memories/task_completion_checklist.md (1)
1-60:⚠️ Potential issue | 🟡 MinorFix markdownlint whitespace issues to keep CI green.
Static analysis hints indicate markdownlint-cli2 warnings for:
- MD022 (blank lines around headings)
- MD031 (blank lines around fenced code blocks)
in this checklist file.Please run the repo’s markdown lint fix (
composer lint:md:fix/composer lint:md) and commit the formatting-only results so CI doesn’t fail on doc style.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.serena/memories/task_completion_checklist.md around lines 1 - 60, Run the repo markdown linter to fix MD022 and MD031 in the "When a Coding Task Is Complete — UnitTestInterface" checklist: execute the project's markdown fix command (composer lint:md:fix or npm/markdownlint-cli2 equivalent), ensure there is a blank line above and below headings and fenced code blocks per markdownlint rules, verify with composer lint:md (or markdownlint-cli2) to confirm MD022/MD031 are resolved, and commit the formatting-only changes.
🧹 Nitpick comments (1)
.serena/memories/project_structure.md (1)
57-116: Optional: keep protocol/spec guidance synchronized with server validation logic.This doc describes WebSocket
actionvalues /category: "sourceDataCheck"/validatestring mapping and selector slugification behavior.Given this is user-facing onboarding material, consider doing a quick “source-of-truth” sync pass to ensure the described
action/payload fields and path-mapping regex transformations still exactly match the server (e.g.,LiturgicalCalendarAPI/src/Health.php).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In @.serena/memories/project_structure.md around lines 57 - 116, The docs may be out of sync with server logic: do a quick source-of-truth sync between this spec and the server code (check Health.php regex/path mapping, RomanMissal::getSanctoraleFileName() missal filename rules, and the client slugification helper slugifySelector in common.js) and update the markdown so the WebSocket action names, required payload fields (e.g., category: "sourceDataCheck", validate formats like proprium-de-sanctis-...), and selector casing instructions exactly match the current implementations; specifically verify the mappings for wider-region-, national-calendar-, diocesan-calendar- transforms, the missal_id → validate logic described, and that consumers must use sourceDataCheck not api_path, then adjust wording/examples to reflect any differences found.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In @.serena/memories/code_style_and_conventions.md:
- Around line 50-54: Update the Auth section to reflect the actual JWT
cookie-based authentication: replace references to HTTP Basic Auth and
password_verify/credentials.php with a description that authentication uses the
JwtAuth class (initialized in admin.php) to validate an HttpOnly cookie named
litcal_access_token, and document required env vars JWT_SECRET and optional
JWT_ALGORITHM (default HS256); remove or replace mentions of includes/auth.php
and credentials.php so the doc matches the implementation.
In @.serena/memories/project_overview.md:
- Around line 37-39: The memory incorrectly states HTTP Basic Auth; update the
Auth section to describe the JWT-based flow used by the app: note that admin.php
calls JwtAuth::init() and JwtAuth::isAuthenticated(), JWT tokens are stored in
the HttpOnly cookie named litcal_access_token, and the JWT secret comes from the
JWT_SECRET environment variable; also mention that the authenticated() function
in includes/auth.php is not used by the live app and, if HTTP Basic Auth exists
only for a legacy endpoint, explicitly document that limited scope instead of
claiming site-wide Basic Auth.
In @.serena/memories/project_structure.md:
- Around line 4-44: Update the opening fenced code block in project_structure.md
from ``` to a language-tagged fence such as ```text to satisfy MD040, then run
markdownlint-cli2 --fix (or your project's markdownlint autofix command) to
correct MD022/MD031 whitespace issues (extra/missing blank lines around headings
and lists); check and adjust the top ASCII tree fence and surrounding blank
lines in the file so the fenced block and nearby headings conform to the
linter's blank-line rules.
In @.serena/memories/suggested_commands.md:
- Around line 3-10: Update the "First-time setup" docs to replace the HTTP Basic
Auth instruction with JWT configuration details: remove or mark credentials.php
as deprecated/unnecessary for admin.php, and instead document that admin.php
authenticates via the litcal_access_token HttpOnly cookie; require setting
JWT_SECRET in .env* (must match the LiturgicalCalendarAPI secret) and note
JWT_ALGORITHM is optional (default HS256), plus add a short note or link
describing the admin login flow that issues the JWT cookie so developers know
how to obtain tokens.
---
Outside diff comments:
In @.serena/memories/project_overview.md:
- Around line 1-45: The markdown file violates markdownlint rules MD022/MD031 —
add blank lines above and below each heading (e.g., "UnitTestInterface — Project
Overview", "Testing capabilities", "Tech Stack", etc.) and ensure fenced
sections (any triple-backtick/code-like blocks or lists that act as fences) are
surrounded by blank lines; then run the repository lint autofix (composer
lint:md or composer lint:md:fix) and commit the resulting changes so CI passes.
In @.serena/memories/task_completion_checklist.md:
- Around line 1-60: Run the repo markdown linter to fix MD022 and MD031 in the
"When a Coding Task Is Complete — UnitTestInterface" checklist: execute the
project's markdown fix command (composer lint:md:fix or npm/markdownlint-cli2
equivalent), ensure there is a blank line above and below headings and fenced
code blocks per markdownlint rules, verify with composer lint:md (or
markdownlint-cli2) to confirm MD022/MD031 are resolved, and commit the
formatting-only changes.
---
Nitpick comments:
In @.serena/memories/project_structure.md:
- Around line 57-116: The docs may be out of sync with server logic: do a quick
source-of-truth sync between this spec and the server code (check Health.php
regex/path mapping, RomanMissal::getSanctoraleFileName() missal filename rules,
and the client slugification helper slugifySelector in common.js) and update the
markdown so the WebSocket action names, required payload fields (e.g., category:
"sourceDataCheck", validate formats like proprium-de-sanctis-...), and selector
casing instructions exactly match the current implementations; specifically
verify the mappings for wider-region-, national-calendar-, diocesan-calendar-
transforms, the missal_id → validate logic described, and that consumers must
use sourceDataCheck not api_path, then adjust wording/examples to reflect any
differences found.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Organization UI
Review profile: CHILL
Plan: Pro
Run ID: 08f620c2-5df3-4d14-a01a-a5af1b07daaf
📒 Files selected for processing (6)
.gitignore.serena/memories/code_style_and_conventions.md.serena/memories/project_overview.md.serena/memories/project_structure.md.serena/memories/suggested_commands.md.serena/memories/task_completion_checklist.md
| ## Auth | ||
| - HTTP Basic Auth on all pages via `includes/auth.php` | ||
| - Credentials loaded from `credentials.php` (gitignored) | ||
| - Use `password_verify()` against hashed values | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, let's see the repository structure
git ls-files | head -20Repository: Liturgical-Calendar/UnitTestInterface
Length of output: 542
🏁 Script executed:
# Check if the memory file exists and read it
cat -n ".serena/memories/code_style_and_conventions.md" 2>/dev/null | head -60Repository: Liturgical-Calendar/UnitTestInterface
Length of output: 3166
🏁 Script executed:
# Search for JWT-related files and implementation
find . -type f \( -name "*.php" -o -name "*.js" -o -name "*.ts" \) | xargs grep -l "JwtAuth\|jwt\|JWT_SECRET" 2>/dev/null | head -20Repository: Liturgical-Calendar/UnitTestInterface
Length of output: 154
🏁 Script executed:
# Look for auth-related files
find . -type f -name "*auth*" | grep -v node_modulesRepository: Liturgical-Calendar/UnitTestInterface
Length of output: 141
🏁 Script executed:
# Read the JwtAuth implementation
cat -n src/JwtAuth.phpRepository: Liturgical-Calendar/UnitTestInterface
Length of output: 6866
🏁 Script executed:
# Read includes/auth.php to see what it does
cat -n includes/auth.phpRepository: Liturgical-Calendar/UnitTestInterface
Length of output: 1241
🏁 Script executed:
# Check if credentials.php exists
ls -la credentials.php 2>&1Repository: Liturgical-Calendar/UnitTestInterface
Length of output: 144
🏁 Script executed:
# Search for JWT_SECRET and cookie configuration
rg "JWT_SECRET|litcal_access_token|password_verify" --type php --type jsRepository: Liturgical-Calendar/UnitTestInterface
Length of output: 523
🏁 Script executed:
# Check which auth mechanism is actually being used in admin.php
cat -n admin.php | head -50Repository: Liturgical-Calendar/UnitTestInterface
Length of output: 2364
🏁 Script executed:
# Search for uses of JwtAuth vs Basic Auth in the codebase
rg "JwtAuth|authenticated\(\)" --type php -B 2 -A 2Repository: Liturgical-Calendar/UnitTestInterface
Length of output: 1877
🏁 Script executed:
# Check .env.example for auth configuration
cat -n .env.exampleRepository: Liturgical-Calendar/UnitTestInterface
Length of output: 1941
Update Auth conventions to document JWT cookie auth (not HTTP Basic Auth).
The Auth section incorrectly documents HTTP Basic Auth via includes/auth.php and credentials.php. The actual implementation uses JWT-based authentication with HttpOnly cookie litcal_access_token, initialized via the JwtAuth class in admin.php.
Update this section to reflect:
- JWT cookie-based auth (not Basic Auth or
password_verify()) - Required environment variables:
JWT_SECRETand optionalJWT_ALGORITHM(default: HS256) - Cookie name:
litcal_access_token(set by API, verified server-side viaJwtAuth)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.serena/memories/code_style_and_conventions.md around lines 50 - 54, Update
the Auth section to reflect the actual JWT cookie-based authentication: replace
references to HTTP Basic Auth and password_verify/credentials.php with a
description that authentication uses the JwtAuth class (initialized in
admin.php) to validate an HttpOnly cookie named litcal_access_token, and
document required env vars JWT_SECRET and optional JWT_ALGORITHM (default
HS256); remove or replace mentions of includes/auth.php and credentials.php so
the doc matches the implementation.
| ## Auth | ||
| HTTP Basic Auth on all pages. Credentials in `credentials.php` (gitignored). Verified via `password_verify()`. | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== Basic Auth: find authenticated() call sites =="
rg -n --hidden --no-ignore-vcs -S 'authenticated\s*\(' .
echo
echo "== Basic Auth: find credentials.php usage =="
rg -n --hidden --no-ignore-vcs -S 'credentials\.php' .
echo
echo "== JWT Auth: find JwtAuth usage and init calls =="
rg -n --hidden --no-ignore-vcs -S 'JwtAuth::(init|isAuthenticated|getToken|verifyToken|isConfigured)' .
echo
echo "== JWT cookie name usage =="
rg -n --hidden --no-ignore-vcs -S 'litcal_access_token' .Repository: Liturgical-Calendar/UnitTestInterface
Length of output: 2700
Fix Auth documentation: the memory incorrectly describes HTTP Basic Auth when the app uses JWT auth.
The memory at lines 37-39 states the UI uses HTTP Basic Auth on all pages with credentials in credentials.php, verified via password_verify(). However, the actual auth flow is JWT-based:
admin.phpcallsJwtAuth::init()andJwtAuth::isAuthenticated()- JWT tokens are stored in the HttpOnly cookie
litcal_access_token - The
authenticated()function inincludes/auth.phpis not invoked anywhere in the live app
Update the memory to document JWT auth, JWT_SECRET env var, and the HttpOnly cookie mechanism. If HTTP Basic Auth still serves a purpose (e.g., for a legacy endpoint), explicitly document that scope instead.
🧰 Tools
🪛 markdownlint-cli2 (0.22.1)
[warning] 39-39: Headings should be surrounded by blank lines
Expected: 1; Actual: 0; Below
(MD022, blanks-around-headings)
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.serena/memories/project_overview.md around lines 37 - 39, The memory
incorrectly states HTTP Basic Auth; update the Auth section to describe the
JWT-based flow used by the app: note that admin.php calls JwtAuth::init() and
JwtAuth::isAuthenticated(), JWT tokens are stored in the HttpOnly cookie named
litcal_access_token, and the JWT secret comes from the JWT_SECRET environment
variable; also mention that the authenticated() function in includes/auth.php is
not used by the live app and, if HTTP Basic Auth exists only for a legacy
endpoint, explicitly document that limited scope instead of claiming site-wide
Basic Auth.
| ## First-time setup | ||
| ```bash | ||
| composer install | ||
| cp .env.example .env.development # then edit | ||
| # Create credentials.php (gitignored) with HTTP Basic Auth users | ||
| yarn install || npm install || bun install # for Playwright (bun.lock present) | ||
| ``` | ||
|
|
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
# First, check if the file exists and read its content
cat ".serena/memories/suggested_commands.md" 2>/dev/null || echo "File not found"Repository: Liturgical-Calendar/UnitTestInterface
Length of output: 2269
🏁 Script executed:
# Search for credentials.php references in the codebase
rg "credentials\.php" --type php --type markdownRepository: Liturgical-Calendar/UnitTestInterface
Length of output: 447
🏁 Script executed:
# Search for JWT authentication implementation
rg -i "jwt" --type php -A 3 -B 1 | head -100Repository: Liturgical-Calendar/UnitTestInterface
Length of output: 4590
🏁 Script executed:
# Search for HTTP Basic Auth implementation
rg -i "basic.*auth|authorization.*basic" --type php -A 3 -B 1Repository: Liturgical-Calendar/UnitTestInterface
Length of output: 63
🏁 Script executed:
# Look for admin.php file and JWT cookie initialization
fd -t f "admin\.php" -x cat -n {}Repository: Liturgical-Calendar/UnitTestInterface
Length of output: 19900
🏁 Script executed:
# Search for litcal_access_token usage
rg "litcal_access_token" --type php -B 2 -A 2Repository: Liturgical-Calendar/UnitTestInterface
Length of output: 515
🏁 Script executed:
# Search for JWT_SECRET and JWT_ALGORITHM env vars
rg "JWT_SECRET|JWT_ALGORITHM" --type php -B 1 -A 1Repository: Liturgical-Calendar/UnitTestInterface
Length of output: 415
Update first-time setup to document JWT authentication instead of HTTP Basic Auth.
The setup instructions direct developers to create credentials.php for HTTP Basic Auth, but the actual admin interface (admin.php) authenticates via JWT tokens in the litcal_access_token HttpOnly cookie. This mismatch will confuse developers during onboarding.
Update the "First-time setup" section to specify JWT configuration:
JWT_SECRETmust be set in.env*(required; must match the LiturgicalCalendarAPI secret)JWT_ALGORITHMis optional (defaults toHS256)- Link to or document the admin login flow that issues the JWT cookie
The credentials.php mechanism appears to be a separate auth system; clarify its purpose (if still in use) or document that it is not needed for the admin interface.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In @.serena/memories/suggested_commands.md around lines 3 - 10, Update the
"First-time setup" docs to replace the HTTP Basic Auth instruction with JWT
configuration details: remove or mark credentials.php as deprecated/unnecessary
for admin.php, and instead document that admin.php authenticates via the
litcal_access_token HttpOnly cookie; require setting JWT_SECRET in .env* (must
match the LiturgicalCalendarAPI secret) and note JWT_ALGORITHM is optional
(default HS256), plus add a short note or link describing the admin login flow
that issues the JWT cookie so developers know how to obtain tokens.
….yml) Follow-up to the memories commit. Persist Serena's auto-generated project config so fresh checkouts and worktrees activate Serena cleanly without regenerating these files: - .serena/.gitignore: ignores transient state (cache/, project.local.yml) - .serena/project.yml: project name, language, encoding for Serena's LSP bootstrapping Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Set per-project initial_prompt that Serena always injects on activation (unlike memories, which load on demand). Captures the small set of project-specific rules where forgetting causes real damage — branch/PR targets, anti-patterns, key invariants. Kept tight on purpose to bound the per-session token cost. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
- Replace machine-specific absolute path in `## Repo Location` (was `/home/johnrdorazio/development/...`) - Label unlabeled fenced code blocks as `text` so MD040 passes and rendering is unambiguous Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 participant
Summary
.worktrees/to.gitignore(project-local git worktrees convention)Why
Serena's
.serena/memories/*.mdfiles capture project-specific knowledge — overview, structure, suggested commands, code style, and a task-completion checklist — that Serena writes during onboarding. Committing these means:Files
.serena/memories/project_overview.md.serena/memories/project_structure.md.serena/memories/suggested_commands.md.serena/memories/code_style_and_conventions.md.serena/memories/task_completion_checklist.mdSerena's inner
.serena/.gitignore(already present in the .serena directory and not part of this PR) excludescache/andproject.local.ymlautomatically, so transient state never gets committed.Test plan
git statusshows clean tree after merge (no untracked.serena/paths showing as needing commit)🤖 Generated with Claude Code
Summary by CodeRabbit
Documentation
Chores