codewhale.history 2.11.19 → 2.12.0

package/CHANGELOG.md

@@ -1,243 +1,255 @@
-# Changelog
-
-All notable changes to the CodeWhale Tools Pack.
-
----
-
-## [2.11.19] — 2026-07-13
-
-### Added
-- README: Added the AGPL license info the npm page
-
-## [2.11.17] — 2026-07-13
-
-### Added
-- README: "Looking for Copilot version" changed to level 2 header
-
-## [2.11.16] — 2026-07-13
-
-### Added
-- README: "Looking for Copilot version" section with link to copilot.tools
-
-## [2.11.15] — 2026-07-11
-
-### Added
-- README: requirements list now includes LLM API key prerequisite
-
-## [2.11.14] — 2026-07-11
-
-### Fixed
-- README: trigger table and theme modifiers now show both spec↔code directions (was only showing spec→code)
-
-## [2.11.13] — 2026-07-11
-
-### Added
-- README: "How to use" section — cd → codewhale → TAB → //trigger
-
-## [2.11.12] — 2026-07-11
-
-### Fixed
-- README: moved AGPL notice to footer (was cluttering npm page header)
-
-## [2.11.11] — 2026-07-11
-
-### Added
-- AGPL copyright headers to all source files (4 JS files, 4 SKILL.md files, instructions; README gets footer notice only)
-
-## [2.11.10] — 2026-07-09
-
-### Changed
-- README: clarified install instructions — navigate to your project folder first
-
-## [2.11.9] — 2026-07-07
-
-### Removed
-- README image (npm doesn't render local files)
-- teach_me-overview.png from npm package (files array)
-- tools-install.js: removed diagram copy step and verification
-
-## [2.11.8] — 2026-07-07
-
-### Changed
-- Moved diagram to package root: teach_me-overview.png
-- package.json: images/ → teach_me-overview.png in files array
-- tools-install.js: copy diagram directly to ~/.codewhale/
-
-## [2.11.7] — 2026-07-07
-
-### Added
-- README: teach-me workflow diagram (images/teach_me-overview.png)
-- package.json: include images/ in "files" array for npm publish
-- tools-install.js: copy images to ~/.codewhale/images/ on install
-
-## [2.11.6] — 2026-07-06
-
-### Added
-- README: "Want to take this further" section — promotes //spec-analysis product
-
-## [2.11.5] — 2026-07-06
-
-### Added
-- README: "Want to take this further" section — promotes //spec-analysis product
-
-## [2.11.3] — 2026-06-24
-
-### Added
-- AGPLv3 license (repo root + package directory)
-- DCO-based CONTRIBUTING.md with sign-off rules
-
-### Changed
-- README: AGPLv3 license badge
-
-## [2.11.2] — 2026-06-24
-
-### Fixed
-- README: move update instructions after install command
-
-## [2.11.1] — 2026-06-24
-
-### Added
-- README: update instructions for existing installations
-
-## [2.11.0] — 2026-06-24
-
-### Added
-- **BA-Gates theme** — document quality analysis for business analysts
-- Loop continuation fix in interactive mode
-
-## [2.10.1] — 2026-06-23
-
-### Added
-- README: Spec theme description — spec-to-code correlation
-
-## [2.10.0] — 2026-06-23
-
-### Added
-- **Spec theme** — spec-to-code traceability via Office documents
-- `codewhale-doc-extract` global binary for Office document extraction
-
-## [2.9.3] — 2026-06-23
-
-### Changed
-- README: removed redundant SOLID subsection (covered by trigger table)
-
-## [2.9.2] — 2026-06-23
-
-### Changed
-- **Restructured `//teach-me`** into two orthogonal dimensions:
-  - **Response modes**: passive, interactive, SOLID
-  - **Content themes**: general, decorators, async, generators, SOLID, spec, ba-gates
-
-## [2.9.1] — 2026-06-23
-
-### Added
-- README: SOLID mode trigger table and how-it-works section
-
-## [2.9.0] — 2026-06-23
-
-### Added
-- **SOLID mode** — anti-pattern reconstruction for teaching design principles
-
-## [2.8.13] — 2026-06-22
-
-### Added
-- README: Contact Developer section
-
-## [2.8.12] — 2026-06-21
-
-### Added
-- README: CodeWhale URL link
-
-## [2.8.11] — 2026-06-21
-
-### Changed
-- `//teach-me`: restore files with `git checkout` for byte-perfect reset after interactive rounds
-
-## [2.8.10] — 2026-06-21
-
-### Changed
-- `//teach-me`: use Skip thinking depth in interactive selection
-- Acknowledged `edit_file` transparency in interactive mode
-
-## [2.8.9] — 2026-06-21
-
-### Changed
-- `//teach-me`: suppress thinking during interactive selection/removal to avoid spoilers
-
-## [2.8.8] — 2026-06-21
-
-### Added
-- `//teach-me`: **interactive (reconstruction) mode** — user edits files live to reconstruct missing code, alongside existing passive quiz mode
-
-## [2.8.7] — 2026-06-21
-
-### Changed
-- `//teach-me`: mandate file re-read before each round for ground-truth accuracy
-
-## [2.8.6] — 2026-06-21
-
-### Changed
-- README: simplified install command — postinstall handles the second step
-
-## [2.8.5] — 2026-06-21
-
-### Fixed
-- Postinstall: use `INIT_CWD` instead of `cwd` for correct workspace detection
-
-## [2.8.4] — 2026-06-21
-
-### Added
-- `postinstall` script to auto-run `codewhale-tools-install`
-
-## [2.8.3] — 2026-06-21
-
-### Added
-- `//tools` now displays README in-session as help text
-
-## [2.8.2] — 2026-06-21
-
-### Added
-- README: expanded After Install section with `//history`, `//snapshot`, `//teach-me` details
-
-## [2.8.1] — 2026-06-21
-
-### Added
-- `//teach-me`: targeted concept drills — `teach me decorators`, `teach me async`, `teach me generators`, etc.
-
-## [2.8.0] — 2026-06-21
-
-### Added
-- **`//teach-me` command** — interactive code quiz that selects random snippets from the current project and quizzes on application logic, language semantics, and documentation quality
-- Trigger configuration in instructions.md
-- Skill installation wiring in tools-install.js
-
-## [2.7.0] — 2026-06-20
-
-### Fixed
-- `//snapshot`: removed stale note overwrite step (notes are session-cached)
-
-## [2.6.0] — 2026-06-20
-
-### Changed
-- `//snapshot on` now overwrites stale caching notes with timestamp convention
-
-## [2.5.0] — 2026-06-20
-
-### Added
-- **`//snapshot` command** — pre-edit file backups with timestamp naming, cross-platform, with retry
-
-## [2.0.0] — 2026-06-19
-
-### Changed
-- Cleaned up installer; code published to npmjs
-- Installs into global npm `node_modules/`
-- Instructions appended to existing `instructions.md` (no longer replaced)
-
-## [1.0.0] — 2026-06-19
-
-### Added
-- Initial release
-- `//tools` — lists all available CodeWhale tools
-- `//history` — lists CodeWhale chat sessions with message count, tokens, and cost
-- Cross-platform installer (`tools-install.js`)
-- Global npm package `codewhale.history`
+# Changelog
+
+All notable changes to the CodeWhale Tools Pack.
+
+---
+
+## [2.12.0] — 2026-07-17
+
+### Added
+- teach-me: New Logic-Paths theme (`teach me logic-paths`) — execution-path tracing
+  from start to end across functions, modules, and systems. Levels 1–2: single-function
+  control flow (branch tracing, dead-code detection). Levels 3–5: cross-function call
+  chains from six start-point types (test, entry, thread, event, pubsub, random).
+  Supports both passive (describe the path) and interactive (fix a path-breaking bug)
+  modes.
+- README: New Features section documenting Logic-Paths theme with level table,
+  start-point types, exercise shapes, and triggers.
+
+## [2.11.19] — 2026-07-13
+
+### Added
+- README: Added the AGPL license info the npm page
+
+## [2.11.17] — 2026-07-13
+
+### Added
+- README: "Looking for Copilot version" changed to level 2 header
+
+## [2.11.16] — 2026-07-13
+
+### Added
+- README: "Looking for Copilot version" section with link to copilot.tools
+
+## [2.11.15] — 2026-07-11
+
+### Added
+- README: requirements list now includes LLM API key prerequisite
+
+## [2.11.14] — 2026-07-11
+
+### Fixed
+- README: trigger table and theme modifiers now show both spec↔code directions (was only showing spec→code)
+
+## [2.11.13] — 2026-07-11
+
+### Added
+- README: "How to use" section — cd → codewhale → TAB → //trigger
+
+## [2.11.12] — 2026-07-11
+
+### Fixed
+- README: moved AGPL notice to footer (was cluttering npm page header)
+
+## [2.11.11] — 2026-07-11
+
+### Added
+- AGPL copyright headers to all source files (4 JS files, 4 SKILL.md files, instructions; README gets footer notice only)
+
+## [2.11.10] — 2026-07-09
+
+### Changed
+- README: clarified install instructions — navigate to your project folder first
+
+## [2.11.9] — 2026-07-07
+
+### Removed
+- README image (npm doesn't render local files)
+- teach_me-overview.png from npm package (files array)
+- tools-install.js: removed diagram copy step and verification
+
+## [2.11.8] — 2026-07-07
+
+### Changed
+- Moved diagram to package root: teach_me-overview.png
+- package.json: images/ → teach_me-overview.png in files array
+- tools-install.js: copy diagram directly to ~/.codewhale/
+
+## [2.11.7] — 2026-07-07
+
+### Added
+- README: teach-me workflow diagram (images/teach_me-overview.png)
+- package.json: include images/ in "files" array for npm publish
+- tools-install.js: copy images to ~/.codewhale/images/ on install
+
+## [2.11.6] — 2026-07-06
+
+### Added
+- README: "Want to take this further" section — promotes //spec-analysis product
+
+## [2.11.5] — 2026-07-06
+
+### Added
+- README: "Want to take this further" section — promotes //spec-analysis product
+
+## [2.11.3] — 2026-06-24
+
+### Added
+- AGPLv3 license (repo root + package directory)
+- DCO-based CONTRIBUTING.md with sign-off rules
+
+### Changed
+- README: AGPLv3 license badge
+
+## [2.11.2] — 2026-06-24
+
+### Fixed
+- README: move update instructions after install command
+
+## [2.11.1] — 2026-06-24
+
+### Added
+- README: update instructions for existing installations
+
+## [2.11.0] — 2026-06-24
+
+### Added
+- **BA-Gates theme** — document quality analysis for business analysts
+- Loop continuation fix in interactive mode
+
+## [2.10.1] — 2026-06-23
+
+### Added
+- README: Spec theme description — spec-to-code correlation
+
+## [2.10.0] — 2026-06-23
+
+### Added
+- **Spec theme** — spec-to-code traceability via Office documents
+- `codewhale-doc-extract` global binary for Office document extraction
+
+## [2.9.3] — 2026-06-23
+
+### Changed
+- README: removed redundant SOLID subsection (covered by trigger table)
+
+## [2.9.2] — 2026-06-23
+
+### Changed
+- **Restructured `//teach-me`** into two orthogonal dimensions:
+  - **Response modes**: passive, interactive, SOLID
+  - **Content themes**: general, decorators, async, generators, SOLID, spec, ba-gates
+
+## [2.9.1] — 2026-06-23
+
+### Added
+- README: SOLID mode trigger table and how-it-works section
+
+## [2.9.0] — 2026-06-23
+
+### Added
+- **SOLID mode** — anti-pattern reconstruction for teaching design principles
+
+## [2.8.13] — 2026-06-22
+
+### Added
+- README: Contact Developer section
+
+## [2.8.12] — 2026-06-21
+
+### Added
+- README: CodeWhale URL link
+
+## [2.8.11] — 2026-06-21
+
+### Changed
+- `//teach-me`: restore files with `git checkout` for byte-perfect reset after interactive rounds
+
+## [2.8.10] — 2026-06-21
+
+### Changed
+- `//teach-me`: use Skip thinking depth in interactive selection
+- Acknowledged `edit_file` transparency in interactive mode
+
+## [2.8.9] — 2026-06-21
+
+### Changed
+- `//teach-me`: suppress thinking during interactive selection/removal to avoid spoilers
+
+## [2.8.8] — 2026-06-21
+
+### Added
+- `//teach-me`: **interactive (reconstruction) mode** — user edits files live to reconstruct missing code, alongside existing passive quiz mode
+
+## [2.8.7] — 2026-06-21
+
+### Changed
+- `//teach-me`: mandate file re-read before each round for ground-truth accuracy
+
+## [2.8.6] — 2026-06-21
+
+### Changed
+- README: simplified install command — postinstall handles the second step
+
+## [2.8.5] — 2026-06-21
+
+### Fixed
+- Postinstall: use `INIT_CWD` instead of `cwd` for correct workspace detection
+
+## [2.8.4] — 2026-06-21
+
+### Added
+- `postinstall` script to auto-run `codewhale-tools-install`
+
+## [2.8.3] — 2026-06-21
+
+### Added
+- `//tools` now displays README in-session as help text
+
+## [2.8.2] — 2026-06-21
+
+### Added
+- README: expanded After Install section with `//history`, `//snapshot`, `//teach-me` details
+
+## [2.8.1] — 2026-06-21
+
+### Added
+- `//teach-me`: targeted concept drills — `teach me decorators`, `teach me async`, `teach me generators`, etc.
+
+## [2.8.0] — 2026-06-21
+
+### Added
+- **`//teach-me` command** — interactive code quiz that selects random snippets from the current project and quizzes on application logic, language semantics, and documentation quality
+- Trigger configuration in instructions.md
+- Skill installation wiring in tools-install.js
+
+## [2.7.0] — 2026-06-20
+
+### Fixed
+- `//snapshot`: removed stale note overwrite step (notes are session-cached)
+
+## [2.6.0] — 2026-06-20
+
+### Changed
+- `//snapshot on` now overwrites stale caching notes with timestamp convention
+
+## [2.5.0] — 2026-06-20
+
+### Added
+- **`//snapshot` command** — pre-edit file backups with timestamp naming, cross-platform, with retry
+
+## [2.0.0] — 2026-06-19
+
+### Changed
+- Cleaned up installer; code published to npmjs
+- Installs into global npm `node_modules/`
+- Instructions appended to existing `instructions.md` (no longer replaced)
+
+## [1.0.0] — 2026-06-19
+
+### Added
+- Initial release
+- `//tools` — lists all available CodeWhale tools
+- `//history` — lists CodeWhale chat sessions with message count, tokens, and cost
+- Cross-platform installer (`tools-install.js`)
+- Global npm package `codewhale.history`

package/README.md

@@ -128,6 +128,7 @@ current project.  Two independent dimensions across five difficulty levels:
 - **SOLID** (`teach me solid`) — Anti-pattern detection and design restoration.
 - **Spec** (`teach me spec`) — Spec-to-code traceability using office docs as source.
 - **BA-Gates** (`teach me ba`) — BA documentation quality analysis (ambiguity, AC completeness, edge case coverage).
+- **Logic-Paths** (`teach me logic-paths`) — Execution-path tracing across functions, modules, and systems.
 
 | Trigger | Response | Theme | What happens |
 |---------|----------|-------|-------------|
@@ -139,6 +140,8 @@ current project.  Two independent dimensions across five difficulty levels:
 | `teach me spec interactive` | interactive | spec | Two directions: spec→code (edit code to satisfy a spec) or code→spec (edit spec to match the code) |
 | `teach me ba` | passive | ba-gates | BA doc fragment; you identify quality gate violations |
 | `teach me ba interactive` | interactive | ba-gates | BA doc with issues; you edit to fix them |
+| `teach me logic-paths` | passive | logic-paths | Start/end points; you trace the execution path |
+| `teach me logic-paths interactive` | interactive | logic-paths | Path broken by a bug; you fix the code |
 
 **Triggers:** `teach me` · `quiz me` · `test my knowledge` · `code quiz` ·
 `drill me`
@@ -153,6 +156,7 @@ current project.  Two independent dimensions across five difficulty levels:
 | Theme | `teach me solid` | Anti-pattern detection — fix degraded design |
 | Theme | `teach me spec` | Spec↔code traceability — either direction (show spec, find the code; or show code, name the requirement) |
 | Theme | `teach me ba` | BA documentation quality analysis |
+| Theme | `teach me logic-paths` | Execution-path tracing across modules and systems |
 | Scope | `teach me services/` | Narrow to a specific file or folder |
 | Concept | `teach me decorators` | Target: decorators, async, generators, context managers, comprehensions, error handling, type hints, threading |
 
@@ -168,7 +172,7 @@ current project.  Two independent dimensions across five difficulty levels:
 
 **Mid-round commands:** `hint` (get a nudge) · `skip` (see the answer) ·
 `next` (draw a new snippet) · `level N` · `easier` · `harder` ·
-`interactive` · `passive` · `solid` · `spec` · `ba` · `done` (verify work) · `stop`
+`interactive` · `passive` · `solid` · `spec` · `ba` · `logic-paths` · `done` (verify work) · `stop`
 
 **At the end** you get a session summary: rounds completed, mode, files covered,
 what you're strong on, what to review, and a suggested next level.
@@ -196,6 +200,43 @@ options. You identify which gates a fragment triggers and describe the developer
 impact. On skip or strike-3, the model presents 2–3 domain-specific rewrites per
 issue with a best-fit recommendation.
 
+## New Features
+
+### Logic-Paths Theme (`teach me logic-paths`)
+
+Execution-path tracing — how control flows through the code from a start point
+to an end point. Levels 1–2 focus on single-function control flow; levels 3–5
+trace cross-function / cross-object call chains.
+
+| Level | Scope | What's quizzed |
+|-------|-------|----------------|
+| 1 | Single function, 5–15 lines, 2–3 branches | Simple if/else, early returns: which branch fires for given inputs? |
+| 2 | Single function, 8–20 lines, nested conditions | Nested if/else, loops, try/except chains: trace the path, identify conditions for reaching specific lines |
+| 3 | 2–4 functions within the same module | Direct call chain: given a start and one end point, trace the sequence |
+| 4 | Cross-module, callbacks/registrations | Callbacks, state machines: sometimes given a start, asked to trace to its natural conclusion |
+| 5 | Multi-file, cross-system dispatch | Threads, pub/sub, event loops, async dispatch across subsystems |
+
+**Start-point types** (randomly selected from your project):
+
+| Type | Example |
+|------|---------|
+| `test` | A test function that exercises the target code |
+| `entry` | Main entry point (`main()`, CLI command) |
+| `thread` | Code launched in a thread or executor |
+| `event` | Event handler / signal callback |
+| `pubsub` | A subscriber or message-queue consumer |
+| `random` | Arbitrary function — "how does execution ever reach this point?" |
+
+**Exercise shapes:** path trace with concrete inputs, condition finder ("what
+must be true to reach line N?"), dead branch detection, start→end call chain,
+and start→natural conclusion (levels 4–5, no end point given).
+
+**Interactive mode:** The model introduces a path-breaking bug (wrong branch
+order, removed call, broken registration, swapped comparison). The code still
+compiles but the path is broken — you find and fix it.
+
+**Triggers:** `teach me logic-paths` · `teach me paths` · `teach me flow`
+
 ## 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.11.19",
+  "version": "2.12.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

@@ -1,6 +1,6 @@
 ---
 name: teach-me
-description: Interactive code-teaching quiz. Selects random snippets from the current project and quizzes the user on application logic, language semantics, or BA documentation quality. Triggered by 'teach me', 'quiz me', 'test my knowledge', 'code quiz', or 'drill me'. Supports difficulty levels 1–5 and four themes: passive (explain), interactive (reconstruct), solid (anti-pattern detection), spec (spec-to-code traceability), and ba-gates (BA documentation quality analysis).
+description: Interactive code-teaching quiz. Selects random snippets from the current project and quizzes the user on application logic, language semantics, or BA documentation quality. Triggered by 'teach me', 'quiz me', 'test my knowledge', 'code quiz', or 'drill me'. Supports difficulty levels 1–5 and six themes: passive (explain), interactive (reconstruct), solid (anti-pattern detection), spec (spec-to-code traceability), ba-gates (BA documentation quality analysis), and logic-paths (execution-flow tracing).
 ---
 
 Copyright (C) 2026 Celestial Consulting Ltd
@@ -34,10 +34,14 @@ current project. Two independent dimensions combine to form each exercise:
   spec → code (show a requirement, ask what code implements it) or code → spec
   (show code, ask what requirement it satisfies).
 - **`ba`** / **`ba-gates`** / **`requirements`** — BA documentation quality analysis.
-  Scans requirements documents (.docx, .pptx, .xlsx, .md, .feature, .txt) and
-  quizzes on three quality gates: ambiguity, acceptance criteria completeness,
-  and edge case coverage. Uses two-pass analysis: regex triage then LLM
-  interpretation per fragment. On skip, presents concrete improvement options.
+   Scans requirements documents (.docx, .pptx, .xlsx, .md, .feature, .txt) and
+   quizzes on three quality gates: ambiguity, acceptance criteria completeness,
+   and edge case coverage. Uses two-pass analysis: regex triage then LLM
+   interpretation per fragment. On skip, presents concrete improvement options.
+- **`logic-paths`** / **`paths`** / **`flow`** — Execution-path tracing. Levels 1–2:
+   single-function control flow (branch tracing, dead-code detection). Levels 3–5:
+   cross-function / cross-object call chains from a start point (test, entry,
+   thread, event, pubsub, or random) to an end point.
 
 | Trigger | Response | Theme | What happens |
 |---------|----------|-------|-------------|
@@ -49,6 +53,8 @@ current project. Two independent dimensions combine to form each exercise:
 | `teach me spec interactive` | interactive | spec | Spec-to-code traceability; you edit code to satisfy a spec, say `done` |
 | `teach me ba` | passive | ba-gates | Present BA doc fragment; you identify quality gate violations |
 | `teach me ba interactive` | interactive | ba-gates | BA doc with quality issues; you edit the doc to fix them, say `done` |
+| `teach me logic-paths` | passive | logic-paths | Present start/end points; you trace the execution path between them |
+| `teach me logic-paths interactive` | interactive | logic-paths | Path broken by a bug; you fix the code to restore correct flow, say `done` |
 
 Level, scope, language, and concept modifiers combine freely with any
 combination above.
@@ -78,6 +84,7 @@ Optionally followed by modifiers:
 - `teach me spec` — spec-to-code traceability theme
 - `teach me ba` / `teach me ba-gates` / `teach me requirements` — BA documentation quality analysis theme
 - `quiz me on requirements` / `ba quality check` — alternative ba-gates triggers
+- `teach me logic-paths` / `teach me paths` / `teach me flow` — execution-path tracing theme
 
 Modifiers combine freely: `teach me decorators level 4`,
 `teach me async services/`, `teach me generators l2`,
@@ -87,7 +94,9 @@ Modifiers combine freely: `teach me decorators level 4`,
 `teach me spec`, `teach me spec interactive`,
 `teach me ba`, `teach me ba level 3`,
 `teach me ba interactive`, `teach me ba <file>`,
-`teach me requirements level 4`
+`teach me requirements 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.
@@ -782,13 +791,287 @@ The improvement options MUST be concrete and domain-specific. Prefer specific da
 
 ---
 
+### 2f. Logic-Paths Theme — Execution-Path Tracing
+
+When content theme is `logic-paths` (triggered by `teach me logic-paths`, `teach me paths`,
+or `teach me flow`), the model quizzes the user on execution paths — how control
+flows through the code from a start point to an end point. Levels 1–2 focus on
+single-function control flow; levels 3–5 trace cross-function / cross-object call
+chains.
+
+Logic-paths theme supports both response modes:
+- **passive + logic-paths** (`teach me logic-paths`): User describes the path in console.
+- **interactive + logic-paths** (`teach me logic-paths interactive`): The model introduces
+  a bug that breaks the path; user fixes the code and says `done`.
+
+#### Level Split
+
+| Level | Scope | What's quizzed |
+|-------|-------|----------------|
+| 1 | Single function, 5–15 lines, 2–3 branches | Simple if/else, early returns: which branch fires for given inputs? What's the return value? |
+| 2 | Single function, 8–20 lines, nested conditions | Nested if/else, loops with break/continue, try/except chains: trace the path, identify conditions for reaching specific lines |
+| 3 | 2–4 functions within the same module | Direct call chain: given a start point and one end point, trace the sequence — which functions fire and in what order? |
+| 4 | Cross-module, callbacks/registrations | Callbacks, state machines, registration patterns: sometimes given a start and asked "trace to its natural conclusion" (no end point provided) |
+| 5 | Multi-file, cross-system dispatch | Threads, pub/sub, event loops, async dispatch: given a start trigger in one subsystem, trace to the observable outcome in another |
+
+#### Exercise Shapes (Random Per Round)
+
+**Levels 1–2:**
+- **Path trace:** "Given these concrete inputs, which branches fire? What path does execution take? What is the final return value?"
+- **Condition finder:** "What condition must be true for execution to reach line N?"
+- **Dead branch:** "Is any code in this function unreachable? Which lines, and why?"
+
+**Levels 3–5:**
+- **Start → End:** Both start and end points given. Trace the exact call chain from A to B.
+- **Start → Natural Conclusion:** Only a start point given. Trace to the natural end — the observable outcome (return, state change, side effect, DB write, log).
+- **Start → End with Conditional Branches:** Trace the path, noting every conditional fork that could divert execution and what determines which branch is taken.
+
+**Levels 4–5:** One or two end points. When the model provides only a start point, the
+question becomes "trace this to its natural conclusion" — the user must identify the
+end point themselves.
+
+#### Start-Point Types
+
+The model randomly selects a start-point type from those available in the project:
+
+| Start type | How the model finds it | Example |
+|---|---|---|
+| `test` | A test function that exercises the target code | `test_calculate_shares_zero_risk()` |
+| `entry` | Main entry point (`if __name__ == "__main__"`, `main()`, CLI command) | `main()` in `cli.py` |
+| `thread` | Code launched in a thread or executor | `Thread(target=watchdog)` |
+| `event` | Event handler / signal callback / listener registration | `button.clicked.connect(handler)` |
+| `pubsub` | A subscriber or message-queue consumer | `@subscribe("order.created")` |
+| `random` | Arbitrary function — "how does execution ever reach this point?" | Any function in the codebase |
+
+#### Discovery (Logic-Paths) — Call-Graph Sketch
+
+Logic-paths discovery is **slower than other themes** because the model must
+understand how code connects — not just index it. The discovery message MUST
+warn the user:
+
+```
+Mapping execution paths across the project. This takes longer than
+standard discovery because I'm tracing call chains, event wiring,
+and cross-module connections. Please wait…
+
+Scanned N files → M functions. Building call-graph sketch…
+Found X start-point candidates across Y types. Ready.
+```
+
+**Discovery steps:**
+
+1. Run standard discovery (file → function index) as in section 1.
+2. **Scan for start-point candidates.** Use `grep_files` for:
+   - Test functions: `def test_`, `it(`, `test(`, `describe(`
+   - Entry points: `if __name__`, `main()`, CLI registrations
+   - Thread spawns: `Thread(`, `threading.Thread`, `executor.submit`
+   - Event/signal wiring: `.connect(`, `.on(`, `.addEventListener`, `signal`
+   - Pub/sub subscriptions: `@subscribe`, `@topic`, `@queue`, `@consumer`
+   - Random: any non-trivial function at the user's level
+3. **Walk each candidate.** For each start-point candidate, read enough of the
+   call chain to identify a meaningful end point — something the start
+   eventually reaches that produces an observable result (return value, state
+   change, side effect, log, DB write).
+4. **Verify the path.** The model MUST walk the entire path itself before
+   presenting it to the user — the path must be real, traceable, and
+   appropriate for the current level.
+5. **Build candidate pool:** `(start_type, start_location, end_location, path_length, level)`.
+   Discard candidates where the model cannot confidently trace the path.
+
+#### Snippet Selection (Logic-Paths)
+
+- **Levels 1–2:** Select functions with branching (if/elif/else, switch/match),
+  early returns, guard clauses, exception handlers, or loops with break/continue.
+  Avoid straight-line single-return functions.
+- **Levels 3–5:** Select from the call-graph candidate pool. Prefer paths that
+  cross at least one meaningful boundary (function call, object handoff, module
+  boundary). For levels 4–5, prefer paths involving callbacks, event dispatch,
+  or async mechanisms.
+
+#### Per-Round Flow (Logic-Paths)
+
+0. **Snapshot git state.** Run `git status --porcelain` on the files the path
+   touches. Note any pre-existing changes.
+1. **Select** a candidate from the pool matching the current level and mode.
+2. **Walk and verify** the path. Re-read the involved files to ensure the
+   path is still accurate.
+3. **Present** the start and end points with enough context for the user
+   to reason about the path.
+4. **Wait** for the user's response.
+5. **Evaluate** the user's trace against the model's verified path.
+6. **Feedback** with targeted nudges (see Logic-Paths Evaluation).
+7. **Restore** (interactive only). `git checkout -- <file>` for byte-perfect
+   reset. If pre-existing uncommitted changes, restore manually via `edit_file`.
+
+#### Thinking Suppression (Logic-Paths)
+
+During steps 1–3 (selection, verification, and presentation), use **Skip**
+thinking — the reasoning block would reveal the correct path and spoil the
+exercise. Resume normal thinking at step 4 (after presentation).
+
+#### Logic-Paths Presentation Format
+
+**Levels 1–2 (passive):**
+
+```
+---
+## Round N — Level X · passive · logic-paths | `path/to/file.py` (lines A–B)
+
+```python
+ 42      risk_amount = capital * (risk_per_trade / 100)
+ 43      price_risk = abs(entry_price - stop_loss)
+ 44      if price_risk == 0:
+ 45          return 0
+ 46      if risk_amount <= 0:
+ 47          return 0
+ 48      shares = int(risk_amount / price_risk)
+ 49      return max(shares, 0)
+```
+
+**Your turn:** (Passive) Trace the execution path for these inputs:
+`capital=0, risk_per_trade=2, entry_price=100, stop_loss=100`.
+Which line does execution reach first? What is the return value? What
+condition caused the early exit?
+
+Type `hint` for a clue, `skip` to see the answer, or `stop` to end.
+---
+```
+
+**Levels 3–5 (passive — start → end):**
+
+```
+---
+## Round N — Level 4 · passive · logic-paths | pubsub → side effect
+
+**Start:** `services/order_handler.py` — `@subscribe("order.created")`
+triggers `handle_new_order()`
+
+**End:** `services/inventory.py::reserve_stock()` reduces `available_quantity`
+by the ordered amount
+
+**Your turn:** (Passive) Trace the path from the pub/sub event arrival to the
+inventory update. Which functions fire, in what order? What objects mediate
+the handoff? Are there any conditional branches along the way that could
+divert execution?
+
+Type `hint` for a clue, `skip` to see the answer, or `stop` to end.
+---
+```
+
+**Levels 4–5 (passive — start only, trace to natural conclusion):**
+
+```
+---
+## Round N — Level 5 · passive · logic-paths | thread → outcome
+
+**Start:** `services/watchdog.py` — `Thread(target=health_check_loop)` is
+spawned during application startup
+
+**End:** Trace this to its natural conclusion. What is the observable outcome
+of this thread's execution? Which functions, modules, and system boundaries
+does it cross?
+
+Type `hint` for a clue, `skip` to see the answer, or `stop` to end.
+---
+```
+
+**Interactive mode (logic-paths):**
+
+The model introduces a **path-breaking bug** — a change that breaks the execution
+flow without making the code obviously wrong. Examples:
+- Swap the order of two conditional branches (wrong branch fires first)
+- Remove a critical function call from the chain
+- Change a registration key so the handler is never wired
+- Introduce a wrong comparison operator that diverts the path
+- Remove a `yield` or `await` that a downstream call depends on
+
+The bug MUST be subtle enough to require the user to trace the path, not just
+spot a syntax error. The code must still parse/compile.
+
+**Interactive presentation format:**
+
+```
+---
+## Round N — Level 4 · interactive · logic-paths | `services/order_handler.py`
+
+**Start:** `services/order_handler.py` — `@subscribe("order.created")`
+triggers `handle_new_order()`
+
+**End:** `services/inventory.py::reserve_stock()` should reduce
+`available_quantity` by the ordered amount — but it never fires.
+
+⚠️ **Interactive — Path Broken.** A bug has been introduced somewhere in the
+execution chain. The code still compiles but the path from start to end is
+broken. Find and fix the bug. When you're done, say **`done`** or
+**`check my work`**.
+
+Type `hint` for a clue, `skip` to see the answer, or `stop` to end.
+---
+```
+
+#### Logic-Paths Evaluation
+
+Evaluate across dimensions scaled to the current level:
+
+| Level | What's assessed |
+|-------|----------------|
+| 1 | Correct branch identification for given inputs; correct return value; awareness of which condition triggered |
+| 2 | Correct nested path; identified all relevant branches; awareness of fall-through and break/continue behavior |
+| 3 | Complete call chain (every function named in order); correct object handoffs; awareness of conditional diversions |
+| 4 | Complete cross-module chain; identified callbacks/registrations; noted where state is passed between modules; identified the logical end point |
+| 5 | Complete multi-system chain; identified dispatch mechanism (thread, pubsub, event loop); noted async synchronization points; understood the architectural flow |
+
+**Outcome levels:**
+
+| Outcome | Criteria | Feedback approach |
+|---------|----------|-------------------|
+| **Complete** | Traced the full path correctly at the current level with awareness of branches and handoffs | Highlight what they caught + 1–2 things to sharpen |
+| **Partial** | Traced some of the path, or missed significant branches/handoffs | Strike-1 or strike-2 nudge toward the missed part |
+| **Missed** | Did not identify the primary path or start/end connection | Strike-2 or strike-3 with full path reveal |
+
+**Interactive mode evaluation** — compare the user's fix against the bug that was introduced:
+- Did they restore the correct path? (Yes — exact / close)
+- Does the path now reach the end point? (Yes / no)
+- Did they fix the right thing, or patch a symptom?
+
+#### Strikes in Logic-Paths
+
+**Strike 1** — Category nudge (don't reveal the answer, just steer):
+```
+Good start, but you're missing part of the chain. Look between [function A]
+and [function C] — what sits in the middle? Also, there's a conditional
+branch you haven't considered.
+```
+
+**Strike 2** — Near-explicit hint (name a specific function or condition):
+```
+You're close. The path goes through `PaymentGateway.authorize()` before
+reaching `InventoryService`. And on line 47 of order_handler.py, there's
+an `if order.total <= 0` guard that short-circuits the path entirely.
+```
+
+**Strike 3** — Reveal the full path and move to the next round:
+```
+Here's the complete execution path:
+
+  handle_new_order()
+  → OrderValidator.validate(order)      # returns ValidationResult
+  → PaymentGateway.authorize(order)     # if total > 0, else return
+  → InventoryService.reserve(items)     # reduces available_quantity
+  → OrderNotifier.send_confirmation()   # side effect: email
+```
+
+After strike 3, proceed directly to the next round.
+
+---
+
 ### 3. Presentation — Show the Snippet
 
 For each round, present the snippet with its filename:
 
 ```
 ---
-## Round N — Level X · [passive|interactive] · [concept|solid|spec|ba-gates] | `path/to/file.py` (lines A–B)
+## Round N — Level X · [passive|interactive] · [concept|solid|spec|logic-paths|ba-gates] | `path/to/file.py` (lines A–B)
 
 ```python
  42  def calculate_position_size(
@@ -818,7 +1101,7 @@ Guidelines:
 - Show the function/class signature with its decorators
 - Show the filename and line range in the header
 - The response mode tag (`· passive` or `· interactive`) always appears in the header
-- The theme/concept tag (`· solid` for SOLID theme, `· spec` for spec theme, `· ba-gates` for BA-Gates theme, or `· decorators` etc. for targeted concept) appears when applicable; omit during free-play standard rounds
+- The theme/concept tag (`· solid` for SOLID theme, `· spec` for spec theme, `· ba-gates` for BA-Gates theme, `· logic-paths` for logic-paths theme, or `· decorators` etc. for targeted concept) appears when applicable; omit during free-play standard rounds
 - If the snippet depends on one obvious external type or constant, include a
   brief inline note
 - **Before presenting, scan for secrets.** Redact API keys, tokens, passwords,
@@ -952,6 +1235,19 @@ documentation quality issues against the Pass 2 generated expected answer:
 
 See section 2e (BA-Gates Theme) for the full strike system and improvement options format.
 
+#### F. Logic-Paths Mode Evaluation
+
+When theme is `logic-paths`, evaluate the user's ability to trace execution paths
+against the level-appropriate criteria in section 2f (Logic-Paths Theme).
+
+| Outcome | Criteria | Feedback approach |
+|---------|----------|-------------------|
+| **Complete** | Traced the full path correctly with awareness of branches and handoffs | Highlight what they caught + 1–2 things to sharpen |
+| **Partial** | Traced some of the path, or missed significant branches/handoffs | Strike-1 or strike-2 nudge toward the missed part |
+| **Missed** | Did not identify the primary path or start/end connection | Strike-2 or strike-3 with full path reveal |
+
+See section 2f (Logic-Paths Theme) for the full strike system and presentation format.
+
 #### Weighted Evaluation for Targeted Concepts
 
 When a concept is targeted (e.g., `teach me decorators`), bias the
@@ -1046,13 +1342,14 @@ explicitly says `stop`.**
 | `solid` / `SOLID` | Switch to SOLID (anti-pattern reconstruction) theme for subsequent rounds. |
 | `spec` | Switch to spec (spec-to-code traceability) theme for subsequent rounds. |
 | `ba` / `ba-gates` / `requirements` | Switch to BA-Gates (BA documentation quality) theme for subsequent rounds. |
-| `done` / `check my work` | (Interactive/SOLID/Spec/BA-Gates mode) Signal that work is complete. Triggers verification. |
+| `logic-paths` / `paths` / `flow` | Switch to logic-paths (execution-path tracing) theme for subsequent rounds. |
+| `done` / `check my work` | (Interactive/SOLID/Spec/BA-Gates/Logic-Paths mode) Signal that work is complete. Triggers verification. |
 | `stop` / `end` | End session. Deliver summary. |
 
 ### 5. Loop — Keep Going
 
 After a successful evaluation or a `next` skip, ask:
-"Another round? (yes / no / level N / interactive / passive / solid / spec / ba / stop)"
+"Another round? (yes / no / level N / interactive / passive / solid / spec / ba / logic-paths / stop)"
 
 After a strike-3 reveal, do **not** ask — proceed directly to the next
 round with:
@@ -1094,6 +1391,24 @@ Gates to strengthen: Edge case coverage (rounds 2, 3)
 Suggested next level: 3 → 4
 ```
 
+For Logic-Paths sessions, the summary covers paths and start-point types instead of gates:
+```
+## Session Summary
+
+Rounds completed: 4
+Theme: logic-paths · Mode: passive · Level: 3
+Paths traced:
+  - test_calculate_shares → PositionSizer.calculate() (round 1 — test start)
+  - main() in cli.py → Database.record_sale() (round 2 — entry start)
+  - @subscribe("order.created") → inventory reserve (round 3 — pubsub start)
+  - Thread(health_check) → SystemMonitor.alert() (round 4 — thread → natural conclusion)
+
+Start-point types covered: test, entry, pubsub, thread
+Paths mastered:          Round 1, 3 ✓
+Paths to strengthen:     Round 2 (missed validation step), Round 4 (missed timeout branch)
+Suggested next level: 3 → 4
+```
+
 ## Multilingual Projects
 
 If the project contains multiple languages, let the user's `teach me <lang>`
@@ -1146,6 +1461,11 @@ criteria for the Mechanics axis:
 - **BA-Gates two-pass integrity.** Pass 1 regex results are filters only — do not present them as answers. Pass 2 LLM interpretation MUST run fresh per fragment at round time. If Pass 2 determines all regex flags are false positives, discard the fragment and select another. Do not fabricate issues.
 - **BA-Gates extraction fallback.** If `codewhale-doc-extract` fails for any office file, note it and skip that file — do not attempt alternative extraction methods. Report skipped files in discovery.
 - **BA-Gates thinking discipline.** Pass 2 analysis runs with Deep/High thinking. Once presentation begins, switch to Skip thinking — never include generated answers or gate locations in reasoning_content after the fragment is shown.
+- **Logic-paths start-point realism.** Only present start/end points that the model has actually verified by walking the path. Do not fabricate or approximate a call chain — if the model cannot confidently trace the path, discard the candidate and select another.
+- **Logic-paths interactive safety.** The path-breaking bug MUST keep the code compilable/parseable. The model MUST NOT introduce syntax errors, delete function signatures, or write code that would crash on import. The bug must be in the logic, not the grammar.
+- **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.
 
 ## Verification
 
@@ -1184,3 +1504,15 @@ After each round, confirm:
 - (BA-Gates theme) `//snapshot on/off` was used in interactive mode for non-git workspaces
 - (BA-Gates theme) Extraction fallback was handled gracefully — skipped files were reported
 - (BA-Gates theme) Thinking suppression was maintained — Pass 2 material was not leaked into reasoning after presentation
+- (Logic-paths theme) Discovery warned the user about longer startup time
+- (Logic-paths theme) Start-point candidates were scanned across test/entry/thread/event/pubsub/random types
+- (Logic-paths theme) The model walked and verified the full path using live file reads before presentation
+- (Logic-paths theme) The start-point type and end-point location were clearly stated in the presentation
+- (Logic-paths theme) For level 4–5 "natural conclusion" rounds, no end point was revealed before evaluation
+- (Logic-paths theme) Exercise shape (path trace, condition finder, dead branch, start→end, start→natural conclusion) was varied across rounds
+- (Logic-paths theme) Interactive mode bugs kept code compilable — no syntax errors introduced
+- (Logic-paths theme) Interactive mode bugs were in logic, not grammar — path-breaking but not crash-causing
+- (Logic-paths theme) Call chain was verified before presentation — no fabricated or approximated paths
+- (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