feat: prefer single-word topic names + clamp future lesson timestamps

Topic naming:
- DEFAULT_PROFILE keys renamed to single most-characterising word
  (software_architecture → architecture, docker_compose merged into docker,
  performance_optimization → performance, linux_cli → linux, html_css → frontend,
  node_js → node, debugging_mindset → debugging, design_patterns → patterns,
  general_engineering → engineering)
- SKILL.md, server.py add_topic docstring, and CLAUDE.md updated with the
  naming rule: use the single most characterising word; strip descriptive
  suffixes (ci_cd_pipeline_design → ci_cd); max 3 words

Timestamp safety:
- Lesson.parse_and_normalize_timestamp now clamps any future timestamp to
  datetime.now(UTC) — lessons can never be stored with a future date
- coach.py rate-limit message improved: displays "in Xm (future timestamp)"
  instead of "-Xm ago" when the last lesson has a future timestamp
- Test fixtures updated to use T00:01-03Z (always-past UTC times on today's date)

Author: UltimaPhoenix

CLAUDE.md

@@ -182,7 +182,7 @@ The `log_lesson` tool accepts this schema:
 {
   "id": "uuid-or-random-string",
   "timestamp": "2025-01-15T20:30:00Z",
-  "topic_id": "python_generators",
+  "topic_id": "python",
   "category": "python",
   "title": "Generator expressions vs list comprehensions",
   "level": "mid",

src/devcoach/SKILL.md

@@ -338,7 +338,7 @@ Call `log_lesson` right after delivering the lesson, without waiting for feedbac
 {
   "id": "unique-slug-or-uuid",
   "timestamp": "2026-04-27T14:30:00Z",
-  "topic_id": "snake_case_identifier",
+  "topic_id": "topic",
   "categories": ["the_topic_category", "architecture"],
   "title": "Lesson title",
   "level": "junior|mid|senior",
@@ -348,6 +348,11 @@ Call `log_lesson` right after delivering the lesson, without waiting for feedbac
 }
 ```
 
+**`topic_id` naming:** use the single most characterizing word for the domain
+(e.g. `sqlite`, `python`, `docker`). For compound concepts with no single-word
+equivalent, keep the essential part — `ci_cd_pipeline_design` → `ci_cd`. Never
+more than 3 words.
+
 Git metadata (`project`, `repository`, `branch`, `commit_hash`, `folder`,
 `repository_platform`) is **auto-detected server-side**. Do not run git commands
 manually. Omitting these fields is correct and will not reduce lesson quality.

src/devcoach/core/coach.py

@@ -50,10 +50,14 @@ def check_rate_limit(conn: sqlite3.Connection) -> RateLimitResult:
                 remaining = settings.min_gap_minutes - elapsed_minutes
                 gap_h, gap_m = divmod(settings.min_gap_minutes, 60)
                 rem_h, rem_m = divmod(int(remaining), 60)
+                if elapsed_minutes < 0:
+                    ago_text = f"in {-elapsed_minutes:.0f}m (future timestamp)"
+                else:
+                    ago_text = f"{elapsed_minutes:.0f}m ago"
                 return RateLimitResult(
                     allowed=False,
                     reason=(
-                        f"Too soon: last lesson {elapsed_minutes:.0f}m ago, "
+                        f"Too soon: last lesson {ago_text}, "
                         f"minimum interval is {gap_h}h {gap_m}m "
                         f"({rem_h}h {rem_m}m remaining)"
                     ),

src/devcoach/core/db.py

@@ -19,31 +19,30 @@
 LEARNING_STATE_PATH = Path.home() / ".devcoach" / "learning-state.md"
 
 DEFAULT_PROFILE: dict[str, int] = {
-    "general_engineering": 8,
-    "software_architecture": 8,
-    "design_patterns": 7,
-    "debugging_mindset": 8,
-    "node_js": 7,
+    "engineering": 8,
+    "architecture": 8,
+    "patterns": 7,
+    "debugging": 8,
+    "node": 7,
     "javascript": 7,
     "typescript": 6,
     "python": 4,
     "django": 3,
     "fastapi": 4,
     "docker": 8,
-    "docker_compose": 8,
     "traefik": 7,
     "coolify": 7,
     "postgresql": 6,
     "redis": 6,
     "git": 7,
     "ci_cd": 6,
     "security": 5,
-    "performance_optimization": 6,
+    "performance": 6,
     "testing": 5,
-    "linux_cli": 7,
+    "linux": 7,
     "networking": 6,
     "react": 5,
-    "html_css": 5,
+    "frontend": 5,
 }
 
 DEFAULT_SETTINGS: dict[str, str] = {

src/devcoach/core/models.py

@@ -41,16 +41,18 @@ class Lesson(BaseModel):
     @field_validator("timestamp", mode="before")
     @classmethod
     def parse_and_normalize_timestamp(cls, v: str | datetime) -> datetime:
-        """Accept any ISO 8601 string or datetime; always return UTC-aware datetime."""
+        """Accept any ISO 8601 string or datetime; always return UTC-aware datetime clamped to now."""
         if isinstance(v, datetime):
-            return v if v.tzinfo else v.replace(tzinfo=UTC)
-        try:
-            dt = datetime.fromisoformat(v)
-            if dt.tzinfo is None:
-                dt = dt.replace(tzinfo=UTC)
-            return dt.astimezone(UTC)
-        except ValueError:
-            raise ValueError(f"Cannot parse timestamp {v!r} — expected ISO 8601")
+            dt = v if v.tzinfo else v.replace(tzinfo=UTC)
+        else:
+            try:
+                dt = datetime.fromisoformat(v)
+                if dt.tzinfo is None:
+                    dt = dt.replace(tzinfo=UTC)
+                dt = dt.astimezone(UTC)
+            except ValueError:
+                raise ValueError(f"Cannot parse timestamp {v!r} — expected ISO 8601")
+        return min(dt, datetime.now(UTC))
 
     @field_serializer("timestamp")
     def serialize_timestamp(self, v: datetime) -> str:

src/devcoach/mcp/server.py

@@ -293,7 +293,8 @@ async def add_topic(
 ) -> bool:
     """Add a new topic to the knowledge map, or update confidence if it already exists.
 
-    topic: topic identifier, e.g. 'rust_lifetimes'
+    topic: topic identifier — prefer a single word (e.g. 'rust', 'sqlite', 'docker');
+      use multiple words only when strictly necessary (e.g. 'ci_cd'); max 3 words
     confidence: initial confidence score 0-10 (default 5)
     group: optional group name; topic appears under 'Other' if omitted
     Returns True on success, False on error.

tests/conftest.py

@@ -18,6 +18,8 @@
 from devcoach.core.models import Lesson
 
 # Use today's date so period="today" filters always match in tests.
+# Times are chosen to be early UTC so they are always in the past regardless of
+# when the test suite runs (midnight-edge risk is acceptable for CI).
 _TODAY = date.today().isoformat()
 
 
@@ -26,7 +28,7 @@
 TEST_LESSONS: list[Lesson] = [
     Lesson(
         id="lesson-sqlite3-row-factory-001",
-        timestamp=f"{_TODAY}T12:00:00Z",
+        timestamp=f"{_TODAY}T00:01:00Z",
         topic_id="sqlite3_row_factory",
         categories=["python", "sqlite", "databases"],
         title="sqlite3.Row: accessing query results by column name",
@@ -36,7 +38,7 @@
     ),
     Lesson(
         id="lesson-sqlite-upsert-patterns-001",
-        timestamp=f"{_TODAY}T16:10:00Z",
+        timestamp=f"{_TODAY}T00:02:00Z",
         topic_id="sqlite_upsert_patterns",
         categories=["python", "sqlite", "databases"],
         title="INSERT OR REPLACE vs ON CONFLICT DO UPDATE",
@@ -53,7 +55,7 @@
     ),
     Lesson(
         id="lesson-sqlite-pragma-introspection-001",
-        timestamp=f"{_TODAY}T17:30:00Z",
+        timestamp=f"{_TODAY}T00:03:00Z",
         topic_id="sqlite_pragma_introspection",
         categories=["python", "sqlite", "databases"],
         title="PRAGMA table_info — zero-dependency schema migrations in SQLite",

tests/test_db_extra.py

@@ -355,7 +355,7 @@ def test_count_lessons_since_future(self, conn):
     def test_get_last_lesson_timestamp(self, conn):
         ts = db.get_last_lesson_timestamp(conn)
         assert ts is not None
-        assert "17:30:00" in ts  # latest lesson in conftest
+        assert "00:03:00" in ts  # latest lesson in conftest
 
     def test_get_last_lesson_timestamp_empty(self, tmp_path):
         path = tmp_path / "empty.db"