docs: move migration and api guidance out of always-loaded CLAUDE.md

[abdulrafey1]

What

Trims the always-loaded root CLAUDE.md by moving two self-contained procedures into files that load on demand, cutting resident context in every session from ~14.8k to ~11.0k characters.

Changes

• docs: move the Alembic procedure (autogenerate mechanics, the two app/analytics lineages, the continuous-aggregate backfill, resolving split heads) into a new database-migrations skill that loads on invocation
• docs(api): move the domain-exception-to-HTTP mapping rules into a new sparkth/api/CLAUDE.md, which loads only when working under that directory
• docs: drop the Red-Green-Refactor enumeration — it restates a generic practice already covered by the superpowers:test-driven-development skill; the TDD directives themselves are unchanged
• docs: fold the duplicate ## GitHub Project Management section into the commit-conventions section that already pointed at the same skill
• docs: add both new files to the Additional Documentation table

Safety-critical prohibitions stay in the root file, always loaded. Never edit an existing migration file. No exceptions. and Never use bare except Exception blocks. are untouched, as are the general exception rules that apply outside the API layer (services, plugins, MCP tools). Only the procedural detail moved.

How to Test

1. Confirm no guidance was lost, only relocated:

   git show --stat HEAD
   git diff origin/main..HEAD -- CLAUDE.md

2. Confirm the safety-critical rules are still in the always-loaded file:

   grep -n "Never edit an existing migration file" CLAUDE.md
   grep -n "Never use bare .except Exception." CLAUDE.md

3. Confirm the new skill is discovered and its frontmatter is valid — start a session in the repo and run /context; database-migrations should appear in the skill listing with its description.
4. Confirm the relative link in the new nested file resolves:

   test -f sparkth/lib/exceptions/handlers.py && echo OK

5. Confirm the nested file only loads under sparkth/api/ — open a session, work with a file outside that directory, and check that sparkth/api/CLAUDE.md is not in context.

Notes

No migration, no breaking change, no env var, no dependency change. Documentation and agent-guidance files only — no runtime code is touched.

This is deliberately standalone and based directly on main, so it can merge independently of the in-flight permission-groups / org-tree PR stack.

This description was written with the assistance of an LLM (Claude).