codewhale.history 2.12.0 → 2.13.0

package/CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to the CodeWhale Tools Pack.
 
 ---
 
+## [2.13.0] — 2026-07-18
+
+### Added
+- teach-me: Persistent score tracking across sessions. At session start, users can
+  opt in to score tracking under a chosen name. Scores are stored per-user in
+  `<workspace>/scores-teach-me/<name>.json`. Returning users see a welcome-back
+  summary with total rounds, sessions, strengths, weaknesses, and a suggested next
+  level. Level defaults to `last_level` for returning users.
+
 ## [2.12.0] — 2026-07-17
 
 ### Added

package/README.md

@@ -237,6 +237,30 @@ compiles but the path is broken — you find and fix it.
 
 **Triggers:** `teach me logic-paths` · `teach me paths` · `teach me flow`
 
+### Persistent Score Tracking
+
+Scores can now be saved across sessions. At the start of each teach-me session,
+you're asked whether to track your scores. If you say yes, you're prompted for
+a name — scores are stored per-user in `<workspace>/scores-teach-me/<name>.json`.
+
+Returning users get a welcome-back summary showing total rounds, sessions,
+strengths, weaknesses, last level played, and a suggested next level.
+
+| Scenario | What happens |
+|---|---|
+| User specifies level (`teach me logic-paths level 4`) | Use level 4 |
+| User doesn't specify, first session | Default level 3 (as today) |
+| User doesn't specify, returning user | Use `last_level` from their score file |
+| Suggested next level | Displayed in welcome-back, but user must explicitly change it (`level 4`) |
+| First-ever session, user says yes to tracking | Create fresh file for that name |
+| First-ever session, user says no to tracking | No file, current behaviour |
+| Returning user, says yes this time | Load existing file, show welcome-back summary, append new session at end |
+| Returning user, says no this time | No update written, current behaviour |
+| Name changes mid-session | Not supported — asked only at session start |
+| `scores-teach-me/` doesn't exist | Create directory |
+| File is corrupted JSON | Warn, start fresh for that name |
+| Multiple names (Alice / Bob) | Separate files, separate stats |
+
 ## Want to take this further
 If you've enjoyed using //teach-me and want to audit your entire specification repository and get a formatted report with readiness scores, band distributions, and ranked improvement recommendations, check out our licensed product //spec-analysis.  Contact the developer for more info.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codewhale.history",
-  "version": "2.12.0",
+  "version": "2.13.0",
   "license":"AGPL-3.0",
   "description": "CodeWhale utility commands: session history, tool listing, file snapshot, interactive code quiz — global install",
   "bin": {

package/skills/teach-me/SKILL.md

@@ -98,8 +98,9 @@ Modifiers combine freely: `teach me decorators level 4`,
 `teach me logic-paths`, `teach me logic-paths level 4`,
 `teach me logic-paths interactive`
 
-If no level is specified, default to **level 3** and adjust based on
-performance across rounds.
+If no level is specified, default to **level 3** for new users and adjust based
+on performance across rounds. For returning users with score tracking enabled,
+default to their `last_level` from the score file (see section 1b).
 
 ## Session Lifecycle
 
@@ -118,6 +119,135 @@ E. Report: "Found ~N candidates across M files. Starting at level X. Ready."
 If the user specified a scope, apply it during discovery. If the user
 specified a language, filter by extension.
 
+### 1b. Identity & Score Tracking
+
+After discovery, before presenting the first round, ask about persistent score
+tracking. Score files are stored per-user in `<workspace>/scores-teach-me/<name>.json`.
+The filename IS the identity — no name field inside the JSON.
+
+**Prompt flow:**
+
+1. **Ask:** "Track your scores across sessions? (yes / no)"
+2. **If no:** Proceed to the first round. No file created, no scores saved at session end.
+3. **If yes:** "What name should I use?"
+4. **Load or create** `scores-teach-me/<name>.json`:
+   - If `scores-teach-me/` doesn't exist: create it (`exec_shell mkdir`).
+   - If the file doesn't exist: create a fresh score file (see format below).
+   - If the file exists: load it, show the welcome-back summary (see below), then proceed.
+   - If the file exists but is corrupted JSON: warn the user, start fresh for that name.
+5. **Track throughout the session:** In memory, record each round's outcome
+   (complete / partial / missed), the files covered, and any strengths/weaknesses
+   observed. At session end, append a session record and write the updated file.
+
+**Level selection with scores enabled:**
+
+| Scenario | What happens |
+|---|---|
+| User specifies level (`teach me logic-paths level 4`) | Use level 4 |
+| User doesn't specify, first session | Default level 3 (as today) |
+| User doesn't specify, returning user | Use `last_level` from their score file |
+| Suggested next level | Displayed in welcome-back, but user must explicitly change it (`level 4`) |
+
+**Session tracking scenarios:**
+
+| Scenario | What happens |
+|---|---|
+| First-ever session, user says yes to tracking | Create fresh file for that name |
+| First-ever session, user says no to tracking | No file, current behaviour |
+| Returning user, says yes this time | Load existing file, show welcome-back summary, append new session at end |
+| Returning user, says no this time | No update written, current behaviour |
+| Name changes mid-session | Not supported — asked only at session start |
+| `scores-teach-me/` doesn't exist | Create directory |
+| File is corrupted JSON | Warn, start fresh for that name |
+| Multiple names (Alice / Bob) | Separate files, separate stats |
+
+**Welcome-back message (returning user):**
+
+When a score file is loaded, present the welcome-back summary after the
+discovery report, before the first round:
+
+```
+Welcome back, <name>! 45 rounds across 8 sessions.
+Last: level 3 logic-paths (passive) — 3/5 complete. Suggested next: level 4.
+Strong on: branch tracing, anti-pattern detection.
+Review: async dispatch, edge case coverage.
+
+Found ~150 candidates across 12 files. Starting at level 3. Ready.
+```
+
+If the returning user specified a different theme or level in this session's
+trigger, adjust the starting level accordingly but still show the historical
+welcome-back context.
+
+**First-session message (new user with tracking):**
+
+```
+Got it, <name>. I'll track your scores in scores-teach-me/<name>.json.
+Found ~150 candidates across 12 files. Starting at level 3. Ready.
+```
+
+**Score file format (`scores-teach-me/<name>.json`):**
+
+```json
+{
+  "stats": {
+    "total_rounds": 45,
+    "total_sessions": 8,
+    "last_level": 3,
+    "suggested_next_level": 4,
+    "themes": {
+      "standard": { "rounds": 20, "sessions": 4 },
+      "solid": { "rounds": 10, "sessions": 2 },
+      "logic-paths": { "rounds": 10, "sessions": 1 },
+      "ba-gates": { "rounds": 5, "sessions": 1 }
+    },
+    "modes": {
+      "passive": { "rounds": 35, "sessions": 6 },
+      "interactive": { "rounds": 10, "sessions": 2 }
+    },
+    "strengths": ["branch tracing", "anti-pattern detection"],
+    "weaknesses": ["async dispatch", "edge case coverage"],
+    "last_session": "2026-07-18"
+  },
+  "sessions": [
+    {
+      "date": "2026-07-18",
+      "theme": "logic-paths",
+      "mode": "passive",
+      "level": 3,
+      "rounds": 5,
+      "complete": 3,
+      "partial": 1,
+      "missed": 1,
+      "suggested_next_level": 4,
+      "files_covered": ["services/order_handler.py", "services/inventory.py"],
+      "start_point_types": ["pubsub", "test"],
+      "strengths": ["direct call chain tracing"],
+      "weaknesses": ["conditional branch awareness"]
+    }
+  ]
+}
+```
+
+**Initial (fresh) score file:**
+
+```json
+{
+  "stats": {
+    "total_rounds": 0,
+    "total_sessions": 0,
+    "last_level": 3,
+    "suggested_next_level": 3,
+    "themes": {},
+    "modes": {},
+    "strengths": [],
+    "weaknesses": [],
+    "last_session": null
+  },
+  "sessions": []
+}
+```
+
 ### 2. Selection — Pick a Snippet
 
 Randomly select a file from the index, then randomly select a function,
@@ -1409,6 +1539,45 @@ Paths to strengthen:     Round 2 (missed validation step), Round 4 (missed timeo
 Suggested next level: 3 → 4
 ```
 
+### Save Score File
+
+When the user said yes to tracking at session start, after delivering the
+end-of-session summary:
+
+1. **Build a session record** from the in-memory round outcomes:
+   - `date`: today's date (YYYY-MM-DD)
+   - `theme`: the theme played (standard, solid, spec, ba-gates, logic-paths)
+   - `mode`: passive or interactive
+   - `level`: the level played
+   - `rounds`: total rounds completed
+   - `complete`, `partial`, `missed`: outcome counts
+   - `suggested_next_level`: from the summary
+   - `files_covered`: list of files touched
+   - `start_point_types`: (logic-paths only) list of start-point types used
+   - `strengths`: concepts consistently identified
+   - `weaknesses`: concepts missed across rounds
+
+2. **Append** the session record to the `sessions` array.
+
+3. **Recalculate stats:**
+   - `total_rounds` += session rounds
+   - `total_sessions` += 1
+   - `last_level`: the level played this session
+   - `suggested_next_level`: from the session summary
+   - `themes.<theme>.rounds` += session rounds
+   - `themes.<theme>.sessions` += 1
+   - `modes.<mode>.rounds` += session rounds
+   - `modes.<mode>.sessions` += 1
+   - `strengths`: merge and deduplicate across sessions
+   - `weaknesses`: merge and deduplicate across sessions
+   - `last_session`: today's date
+
+4. **Write** the updated file with `write_file` to `scores-teach-me/<name>.json`.
+
+5. **Confirm:** "Scores saved for <name>."
+
+If the user said no to tracking at session start, skip this step entirely.
+
 ## Multilingual Projects
 
 If the project contains multiple languages, let the user's `teach me <lang>`
@@ -1466,6 +1635,11 @@ criteria for the Mechanics axis:
 - **Logic-paths verification before presentation.** The model MUST walk the full path using live file reads before presenting it — do not rely on discovery-stage analysis. Code may have changed between discovery and the current round.
 - **Logic-paths concurrent safety.** If the project uses multi-threading, multi-processing, or async, clearly explain which parts of the path execute sequentially and which may race or interleave. State the model's assumptions about scheduling.
 - **Logic-paths thinking discipline.** During selection and path verification (before presentation), use Skip thinking — never include the correct path, start/end points, or the bug location in reasoning_content after the round is presented.
+- **Score tracking opt-in.** Always ask before tracking. Never assume — the user must explicitly say yes and provide a name. If they say no, do not create or write any score file.
+- **Score file identity.** The filename IS the identity. Do not embed a name field inside the JSON. Name is derived from the filename: `scores-teach-me/<name>.json`.
+- **Score file location.** Always write to `<workspace>/scores-teach-me/<name>.json`. Never write outside the workspace. Create the `scores-teach-me/` directory if it doesn't exist.
+- **Score file integrity.** Read the file with `read_file` before appending. If the JSON is corrupted, warn the user and start fresh. Never silently overwrite a valid score file due to a parse error.
+- **Score file privacy.** The score file contains no PII beyond the user's chosen name. Do not include email addresses, full names, or any other identifying information unless the user explicitly provides it as their name.
 
 ## Verification
 
@@ -1516,3 +1690,18 @@ After each round, confirm:
 - (Logic-paths theme) The full path was revealed on skip or strike-3 with function names in order
 - (Logic-paths theme) Modified files were restored with `git checkout` on round end (or `edit_file` if pre-existing changes)
 - (Logic-paths theme) Thinking suppression was maintained — path, start/end points, and bug locations were not leaked into reasoning after presentation
+- (Score tracking) User was asked "Track your scores?" before the first round
+- (Score tracking) If user said yes, they were prompted for a name
+- (Score tracking) `scores-teach-me/` directory was created if it didn't exist
+- (Score tracking) Fresh score file was created for new users with correct initial format
+- (Score tracking) Existing score file was loaded and welcome-back summary shown for returning users
+- (Score tracking) If user said no, no score file was created or written
+- (Score tracking) Level defaulted to `last_level` for returning users (unless user overrode)
+- (Score tracking) Suggested next level was displayed but NOT auto-applied
+- (Score tracking) Session record was appended to `sessions` array on session end
+- (Score tracking) Stats were recalculated correctly after appending (totals, themes, modes)
+- (Score tracking) Strengths and weaknesses were merged and deduplicated across sessions
+- (Score tracking) Corrupted JSON was detected, user was warned, and a fresh file was created
+- (Score tracking) Score file was written to `<workspace>/scores-teach-me/<name>.json`
+- (Score tracking) "Scores saved for <name>" confirmation was shown on session end
+- (Score tracking) No PII beyond the user's chosen name was stored in the score file