refactor: make RECOMMENDATIONS.md forward-looking only

- Add Philosophy blockquote: recommendations only, not changelog
- Replace "Open Questions" with "Recommended Improvements" (delete completed, don't strikethrough)
- Replace "Change Log" with "Deployment Notes"
- Add RECOMMENDATIONS.md Cleanup Rules to status-update-checklist
- Add docs/phases-plan.md to phase transition checklist
- Add strikethrough grep check to verification commands

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

.claude/status-update-checklist.md

@@ -7,11 +7,11 @@ AI agents and developers should follow this checklist to prevent drift between f
 
 ## When to Use This Checklist
 
-| Trigger | Scope |
+| Trigger                                        | Scope                                       |
-|---------|-------|
+| ---------------------------------------------- | ------------------------------------------- |
-| **Phase transition** (e.g., Phase 0 → Phase 1) | Full checklist — all files |
+| **Phase transition** (e.g., Phase 0 → Phase 1) | Full checklist — all files                  |
-| **Milestone completed** within a phase | Sections 1–3 only |
+| **Milestone completed** within a phase         | Sections 1–3 only                           |
-| **Architecture decision locked** | RECOMMENDATIONS.md + new ADR in `docs/adr/` |
+| **Architecture decision locked**               | RECOMMENDATIONS.md + new ADR in `docs/adr/` |
 
 ---
 
@@ -20,24 +20,34 @@ AI agents and developers should follow this checklist to prevent drift between f
 Run every item when the project moves to a new phase.
 
 ### 1. RULES.md
+
 - [ ] Update section 6.2: change `Current phase: Phase N` to the new phase
 
 ### 2. README.md
+
 - [ ] Update "Current Status" block (phase badge and status line)
 - [ ] Update footer status line at the bottom of the file
 
 ### 3. DOCS.md
+
 - [ ] Update footer: `**Last Updated:** Phase N (Description)`
 
 ### 4. RECOMMENDATIONS.md
+
 - [ ] Update `Current phase` field in section 1
-- [ ] Add entry to section 6 (Change Log)
+- [ ] Update status line in header blockquote
+- [ ] Update section 5 (Recommended Improvements) — remove completed items, add new recommendations
+- [ ] **Run cleanup** (see RECOMMENDATIONS.md Cleanup Rules below)
 
 ### 5. docs/phases-plan.md
+
 - [ ] Update `**Phase:**` and `**Status:**` in the header
 - [ ] Mark completed phase tasks as done
+- [ ] Update "Current Status" section with resolved/remaining issues
+- [ ] Update "Next Steps" section to reflect what's actually next
 
 ### 6. Architecture docs (if phase affects them)
+
 - [ ] `docs/frontend/architecture.md` — lock decisions after Phase 1
 - [ ] `docs/backend/architecture.md` — lock decisions after Phase 1
 - [ ] Archive `docs/frontend/FRONTEND_ARCHITECTURE_PLAN.md` after Phase 1
@@ -49,14 +59,62 @@ Run every item when the project moves to a new phase.
 Run when a significant milestone is completed within the current phase.
 
 ### 1. RECOMMENDATIONS.md
-- [ ] Add entry to section 6 (Change Log)
+
-- [ ] Update section 5 (Open Questions) — remove resolved items
+- [ ] Remove completed items from section 5 (don't strikethrough — delete them)
+- [ ] Add new recommendations if audit/review produced them
+- [ ] **Run cleanup** (see RECOMMENDATIONS.md Cleanup Rules below)
 
 ### 2. README.md
+
 - [ ] Update "Current Status" block if progress indicators changed
 
 ### 3. docs/phases-plan.md
+
 - [ ] Mark completed tasks
+- [ ] Update "Current Status" section
+
+---
+
+## RECOMMENDATIONS.md Cleanup Rules
+
+**Core principle:** RECOMMENDATIONS.md = "What to do next" + "Locked decisions", NOT "What we did".
+
+### What BELONGS in RECOMMENDATIONS.md
+
+- Project context and locked stack decisions (sections 1–4)
+- Actionable recommendations for improvements (section 5)
+- Active deployment concerns (section 6)
+- ADR links (section 7)
+- 1-line status summary in header blockquote (e.g., "Phase 3 complete. 16 P3 items remain.")
+
+### What does NOT belong in RECOMMENDATIONS.md
+
+- Detailed lists of completed/resolved tasks
+- Strikethrough items (~~resolved item~~) — delete them, don't cross out
+- Changelog / history of changes — use git history instead
+- Sections titled "COMPLETE" with detailed breakdowns
+- Duplicate information about accomplished work
+
+### Where to put completed work instead
+
+- **Git commit messages** — detailed implementation notes
+- **docs/phases/** — phase overview files
+- **docs/improvements/** — improvement summaries
+- **README.md** — brief high-level status in "Current Status" section
+
+### When to clean up
+
+- Every time a phase/milestone completes (mandatory)
+- If file shows strikethrough or "RESOLVED" items
+- If file exceeds 200 lines (target: ~150 lines)
+- If file reads like a changelog rather than a recommendations list
+
+### Red flags (cleanup needed)
+
+- Sections with ~~strikethrough~~ resolved items
+- Sections titled "COMPLETE: [Detailed list]"
+- Multiple paragraphs describing finished work
+- Same completed work mentioned in 2+ places
 
 ---
 
@@ -70,6 +128,9 @@ grep -rn "Phase [0-4]" RULES.md README.md DOCS.md RECOMMENDATIONS.md docs/phases
 
 # Check for stale status markers
 grep -rn "Status.*Draft\|Status.*WIP\|Status.*Complete" docs/ RECOMMENDATIONS.md
+
+# Check for strikethrough items that should have been removed
+grep -rn "~~.*~~" RECOMMENDATIONS.md
 ```
 
 ---
@@ -80,3 +141,4 @@ grep -rn "Status.*Draft\|Status.*WIP\|Status.*Complete" docs/ RECOMMENDATIONS.md
 - **Concrete** — update actual sections listed above, not vague references
 - **Verifiable** — run the grep commands to confirm consistency
 - **Single source of truth** — `RULES.md` section 6.2 is the canonical phase indicator
+- **Forward-looking** — RECOMMENDATIONS.md focuses on what to do next, not what was done

RECOMMENDATIONS.md

@@ -1,69 +1,90 @@
 # Project-Specific Recommendations & Overrides
 
-This file is the project-specific layer on top of the generic template.  
+This file is the project-specific layer on top of the generic template.
 Humans and AI agents should treat it as the **single place to record locked decisions, non‑negotiable constraints, and intentional deviations** from `docs/` guidance.
 
 Update this file whenever you make a decision that changes the stack, scope, constraints, or any recommendation in `docs/`.
 
+> **Philosophy:** This file contains **recommendations** (what to do next) and **locked decisions** (what was agreed upon). It is NOT a changelog or accomplishments log. Keep completed work in git history, `docs/phases/`, and `docs/improvements/`.
+
 ---
 
 ## 1. Project Context (fill in)
-- **Domain / product type:** _[e.g., customer support AI, compliance assistant, content classifier]_  
+
-- **Chosen archetype:** _[A–E from `/docs/archetypes.md`]_  
+- **Domain / product type:** _[e.g., customer support AI, compliance assistant, content classifier]_
-- **Modules in scope:** _[core AI, integrations, pipeline, human feedback, reporting, billing, tenancy, events, queues]_  
+- **Chosen archetype:** _[A–E from `/docs/archetypes.md`]_
-- **Primary users:** _[roles/personas]_  
+- **Modules in scope:** _[core AI, integrations, pipeline, human feedback, reporting, billing, tenancy, events, queues]_
-- **Key success metrics:** _[latency, accuracy, cost, adoption, etc.]_  
+- **Primary users:** _[roles/personas]_
-- **Current phase:** _Phase 0 / 1 / 2 / 3 / 4_  
+- **Key success metrics:** _[latency, accuracy, cost, adoption, etc.]_
+- **Current phase:** _Phase 0 / 1 / 2 / 3 / 4_
 - **Repos/services in scope:** _[monorepo, separate FE/BE, workers, etc.]_
 
 ## 2. Locked Stack Decisions (override template here)
+
 If a choice is not listed here, the default recommendations in `docs/` apply.
 
 **Frontend**
-- **Framework:** _Next.js (App Router)_ / _other_  
+
-- **Language:** _TypeScript_ / _other_  
+- **Framework:** _Next.js (App Router)_ / _other_
-- **Styling:** _Tailwind CSS_ / _other_  
+- **Language:** _TypeScript_ / _other_
-- **Server/Client data layer:** _React Query / SWR / other_  
+- **Styling:** _Tailwind CSS_ / _other_
-- **Forms & validation:** _React Hook Form + Zod_ / _other_  
+- **Server/Client data layer:** _React Query / SWR / other_
+- **Forms & validation:** _React Hook Form + Zod_ / _other_
 - **Auth client:** _Clerk / Auth.js / other_
 
 **Backend**
-- **Runtime/language:** _Node.js (LTS) + TypeScript_ / _other_  
+
-- **Framework:** _Express / Fastify / other_  
+- **Runtime/language:** _Node.js (LTS) + TypeScript_ / _other_
-- **Database:** _Postgres_ / _other_ (vector search: _pgvector_ / _other_)  
+- **Framework:** _Express / Fastify / other_
-- **Queues/workers:** _BullMQ (Redis)_ / _other_  
+- **Database:** _Postgres_ / _other_ (vector search: _pgvector_ / _other_)
-- **LLM provider & helper:** _Single abstraction (e.g., `callLLM()`)_, provider _[fill in]_  
+- **Queues/workers:** _BullMQ (Redis)_ / _other_
+- **LLM provider & helper:** _Single abstraction (e.g., `callLLM()`)_, provider _[fill in]_
 - **File/storage:** _S3/Supabase Storage/local_ / _other_
 
 **Infra / DevOps**
-- **Hosting/deploy:** _[Vercel/Fly/K8s/etc.]_  
+
-- **CI/CD:** _[GitHub Actions/GitLab/etc.]_  
+- **Hosting/deploy:** _[Vercel/Fly/K8s/etc.]_
-- **Observability:** _[Sentry/OTel/Prometheus/etc.]_  
+- **CI/CD:** _[GitHub Actions/GitLab/etc.]_
+- **Observability:** _[Sentry/OTel/Prometheus/etc.]_
 - **Environments:** _dev/stage/prod_ (or specify)
 
 ## 3. Non‑Negotiable Constraints (add to RULES scope)
-- **Compliance/regulation:** _[PII/PHI/PCI, SOC2, GDPR, etc.]_  
+
-- **Data residency/retention:** _[regions, retention window]_  
+- **Compliance/regulation:** _[PII/PHI/PCI, SOC2, GDPR, etc.]_
-- **Performance/SLOs:** _[e.g., p95 < X ms, batch window]_  
+- **Data residency/retention:** _[regions, retention window]_
-- **Cost limits:** _[monthly LLM budget, infra cap]_  
+- **Performance/SLOs:** _[e.g., p95 < X ms, batch window]_
-- **Target platforms:** _[browsers/devices, locales]_  
+- **Cost limits:** _[monthly LLM budget, infra cap]_
+- **Target platforms:** _[browsers/devices, locales]_
 - **Repository constraints:** _[additional forbidden commands, branching rules, etc.]_
 
 ## 4. Deviations From Template (explicit trade-offs)
+
 List any intentional departures from `docs/` recommendations and why.
 
 - _[Decision]_ → _[Why]_ → _[Migration/rollback plan if relevant]_
 
-## 5. Open Questions / To Confirm
+## 5. Recommended Improvements
-- _[Unresolved item]_ → _[owner]_ → _[ETA]_
 
-## 6. Change Log (optional)
+<!--
-- _YYYY‑MM‑DD_: _[decision summary]_  
+  This section is for ACTIONABLE recommendations — things to do next.
+  When an item is completed, REMOVE it from here (don't strikethrough).
+  Record completed work in git commits and docs/phases/ instead.
+-->
+
+_[Add audit findings, improvement suggestions, and next steps here. Group by category if needed.]_
+
+## 6. Deployment Notes
+
+<!-- Active deployment concerns only. Remove items once deployed and verified. -->
+
+_[Pre-deploy checklist items, migration scripts, environment changes needed]_
 
 ## 7. Architecture Decision Records (ADRs)
+
 Record major decisions and their rationale in `docs/adr/`.
 
 Example ADRs you may need:
+
 - _ADR: modular monolith vs microservices_
 - _ADR: vector storage choice (pgvector vs external)_
 - _ADR: billing model/provider_
@@ -71,4 +92,5 @@ Example ADRs you may need:
 - _ADR: auth/tenancy model_
 
 Once accepted, link ADRs here:
+
 - `docs/adr/0001-<title>.md` — _accepted_