@mriekki/lean 0.4.3 → 0.4.5

package/assets/generated/core/core/process/DATABASE_LEARNING_WORKBENCH.md

@@ -2,7 +2,7 @@
 
 The Database Learning Workbench is the reusable Lean learning contract behind `/db-lab`. It makes database behavior that frameworks and ORMs often hide visible enough to inspect, explain, debug, and defend.
 
-It is project-aware rather than a generic SQL course: use the current repository's domain, schema, migrations, ORM mappings, queries, and safe development/test database evidence as the curriculum.
+It is project-aware rather than a generic SQL course: use the **current** repository's domain, schema, migrations, ORM mappings, queries, and safe development/test database evidence as the curriculum.
 
 Learning remains optional and never changes engineering delivery state.
 
@@ -12,7 +12,9 @@ Use `/coach` for explanation, adaptive questioning, and gap assessment. Use `/db
 
 ```text
 /coach database design
+/db-lab
 /db-lab schema
+/db-lab changes <work-item>
 /db-lab trace <query/file/symbol>
 /db-lab plan <query>
 /db-lab debug <symptom/query>
@@ -20,10 +22,13 @@ Use `/coach` for explanation, adaptive questioning, and gap assessment. Use `/db
 /db-lab interview database
 ```
 
+Invoking `/db-lab` means **inspect current evidence and show the current view**. The learner should not need to remember to refresh, rebuild, or manually maintain an ER diagram.
+
 Natural-language arguments are preferred over rigid syntax. Examples:
 
 ```text
 /db-lab show me how Recipes and Ingredients are related
+/db-lab changes WI-24
 /db-lab trace the EF query used by GetWeeklyMealPlan
 /db-lab why is this query scanning MealPlanItems
 /db-lab show which indexes this query actually uses
@@ -31,7 +36,22 @@ Natural-language arguments are preferred over rigid syntax. Examples:
 /db-lab give me a database-design interview based on this domain
 ```
 
-## SQLite interactive workbench — V1
+## Current-by-default artifact lifecycle
+
+Generated workbench HTML/JSON is a disposable projection:
+
+```text
+current safe database/repository evidence
+→ inspect schema / ORM / migrations / queries
+→ build current learning model
+→ generate current interactive view
+```
+
+The database/repository evidence remains authoritative. An older browser tab is not authoritative. Run the lab again and it produces the current view.
+
+When a previous disposable snapshot is available it may help explain what changed, but never outranks current physical/ORM/migration evidence.
+
+## SQLite interactive workbench
 
 Greenfield consumers that include the Core learning payload receive:
 
@@ -39,13 +59,14 @@ Greenfield consumers that include the Core learning payload receive:
 tools/lean-db-lab/sqlite-workbench.py
 ```
 
-The tool is dependency-free Python and opens SQLite databases read-only. It generates a self-contained interactive `index.html` and a machine-readable `workbench.json`.
+The tool is dependency-free Python and opens SQLite databases read-only. It generates a self-contained interactive `index.html` and machine-readable `workbench.json`.
 
-### PowerShell example
+### PowerShell
 
-From the repository root, using a known development/test SQLite file:
+From the repository root, using a **known safe development/test** SQLite file:
 
 ```powershell
+Set-Location D:\Projects\<repo>
 $out = Join-Path $env:TEMP "lean-db-lab"
 python .\tools\lean-db-lab\sqlite-workbench.py export `
   --db .\.data\app.db `
@@ -53,19 +74,20 @@ python .\tools\lean-db-lab\sqlite-workbench.py export `
 Start-Process (Join-Path $out "index.html")
 ```
 
-Use the actual project database path; `.data/app.db` is only an example. Do not point the learning tool at Production data.
+`.data/app.db` is only an example. Use the actual project development/test database path. Never point the learning tool at Production.
 
-### macOS/Linux example
+### macOS/Linux
 
 ```bash
+cd /path/to/repo
 out="${TMPDIR:-/tmp}/lean-db-lab"
 python3 tools/lean-db-lab/sqlite-workbench.py export \
   --db .data/app.db \
   --out "$out"
-open "$out/index.html"  # macOS; use the local browser command appropriate to the environment
+open "$out/index.html" 2>/dev/null || xdg-open "$out/index.html"
 ```
 
-### Add query-to-ERD evidence
+### Query-to-ERD evidence
 
 Create a disposable query-evidence JSON file from captured or otherwise verified SQL:
 
@@ -81,7 +103,7 @@ Create a disposable query-evidence JSON file from captured or otherwise verified
 ]
 ```
 
-Then regenerate the workbench:
+Run the workbench with that evidence:
 
 ```powershell
 $out = Join-Path $env:TEMP "lean-db-lab"
@@ -92,11 +114,11 @@ python .\tools\lean-db-lab\sqlite-workbench.py export `
 Start-Process (Join-Path $out "index.html")
 ```
 
-The query-evidence file and generated workbench are learning artifacts. Keep them disposable/local unless the project explicitly chooses to make a sanitized artifact durable.
+Each invocation produces the current view. The query-evidence file and generated workbench stay disposable/local unless the project explicitly chooses a sanitized durable artifact.
 
-### What the V1 viewer shows
+## What the interactive viewer shows
 
-The SQLite V1 workbench supports:
+The SQLite workbench supports:
 
 - tables and views;
 - columns, types, nullability, and primary-key participation;
@@ -105,8 +127,8 @@ The SQLite V1 workbench supports:
 - junction-table candidates, clearly labeled as a heuristic rather than domain truth;
 - clickable tables, columns, and indexes with a learning/details panel;
 - query selection and highlighting of referenced tables;
-- highlighting of relationship edges when both related tables participate in the selected query;
-- highlighting of qualified query columns when resolvable;
+- relationship-edge highlighting when both related tables participate;
+- qualified query-column highlighting when resolvable;
 - `EXPLAIN QUERY PLAN` evidence for parameterized `SELECT`/`WITH` queries;
 - a distinction between indexes selected by the planner and indexes that are merely plausible candidates/relevant to highlighted columns.
 
@@ -114,7 +136,7 @@ The viewer does not claim to understand arbitrary SQL perfectly. SQL-to-table/co
 
 ## What to expect from `/db-lab`
 
-A useful Database Lab session follows evidence rather than guesses:
+A useful session follows evidence rather than guesses:
 
 ```text
 repository intent
@@ -126,85 +148,75 @@ repository intent
 → explanation or exercise
 ```
 
-The exact evidence depends on the stack. The lab should explicitly state which layers were verified and which were inferred.
-
-## Example 1 — explore the schema
+Explicitly state which layers were verified and which were inferred.
 
-Prompt:
+Where useful, distinguish:
 
 ```text
-/db-lab schema
+DOMAIN MODEL
+ORM MODEL
+PHYSICAL MODEL
 ```
 
-Expected learning flow:
+## Change-focused learning
 
-1. Identify the configured development/test database and relevant ORM/migration artifacts.
-2. Build the table/entity/relationship picture from safe evidence.
-3. Show primary keys, foreign keys, nullability, constraints, and indexes.
-4. Explain important relationship cardinalities.
-5. Compare Domain Model, ORM Model, and Physical Model where they differ.
-6. Ask one or two high-value questions, such as why a junction table exists or what invariant belongs in the database.
+Prompt:
 
-With SQLite, use the distributed workbench when a safe local database is available. Selecting an index should explain its columns, uniqueness, how SQLite created it, and whether the active query plan actually selected it.
+```text
+/db-lab changes WI-24
+```
 
-## Example 2 — Entity Framework to raw SQL
+Use the accepted/delivered change set plus current database evidence. Explain relevant changes to:
 
-Suppose application code contains:
+- entities/tables and columns;
+- primary/foreign/unique/check constraints;
+- nullability and cascade behavior;
+- indexes and access paths;
+- ORM mappings and translation behavior;
+- migrations/DDL and data-safety implications;
+- query paths;
+- transactions/concurrency.
 
-```csharp
-var recipes = await db.Recipes
-    .Include(r => r.Ingredients)
-    .Where(r => r.IsFavorite)
-    .OrderBy(r => r.Name)
-    .ToListAsync();
-```
+A changed entity/migration/query file proves that database-related code was touched. It does **not** by itself prove that the physical database changed. Verify the physical layer when safe evidence is available.
 
-Prompt:
+A good learning summary connects the change to its consequence:
 
 ```text
-/db-lab trace this EF query
+added relationship
+→ new FK/invariant
+→ new join/access path
+→ possible index consideration
+→ migration/data compatibility question
 ```
 
-The lab should connect:
+## Entity Framework to raw SQL
+
+For EF Core, connect:
 
 ```text
 LINQ / EF expression
-→ translation preview when available
-→ captured executed SQL when available
+→ translation preview such as ToQueryString() when appropriate
+→ captured actual DbCommand when available
 → parameters
 → tables and relationships
 → provider query plan
 → indexes selected by the planner
-→ result materialization
-```
-
-Important teaching point: a translation preview and an actually executed command are different kinds of evidence. Label them separately.
-
-For EF Core, `ToQueryString()` can help inspect translation. Framework-supported command logging/interception can provide evidence of the actual `DbCommand`. The SQLite workbench consumes captured SQL; it does not replace EF command capture.
-
-## Example 3 — query-to-ERD highlighting
-
-Prompt:
-
-```text
-/db-lab trace GetWeeklyMealPlan and show it on the ERD
+→ result materialization/tracking
 ```
 
-For a query that touches `MealPlans`, `MealPlanItems`, and `Recipes`, the workbench highlights those tables. If both ends of an FK relationship participate, the corresponding relationship edge is emphasized. Qualified columns found in the query are highlighted in their table cards.
+Translation preview and an actually executed command are different evidence. Label them separately. Use supported logging/interception for executed-command evidence; the SQLite workbench consumes captured SQL and does not replace EF command capture.
 
-If `EXPLAIN QUERY PLAN` shows an index was actually used, the viewer marks it as **planner selected**. If an index's leading column matches highlighted query columns but the planner did not select it, the viewer can mark it as a **candidate/relevant** index without claiming usage.
+Apply the same principle to other ORMs using framework-supported mechanisms.
 
-Selecting a table, column, or index opens a learning/details panel. The query panel shows the captured SQL and SQLite plan details alongside the ERD.
+## Query-to-ERD highlighting
 
-If the interactive viewer is unavailable, use a temporary Mermaid/text diagram and explain that the rich query-to-ERD interaction is unavailable in the current checkout.
+For a query touching `MealPlans`, `MealPlanItems`, and `Recipes`, highlight those tables. If both ends of an FK relationship participate, emphasize the edge. Highlight resolvable qualified columns.
 
-## Example 4 — query-plan debugging
+If `EXPLAIN QUERY PLAN` says an index was used, mark it **planner selected**. An index whose leading column appears relevant but was not selected can be shown as **candidate/relevant**, never as used.
 
-Prompt:
+If the interactive viewer is unavailable, use a temporary Mermaid/text diagram and clearly label the fallback.
 
-```text
-/db-lab why is this query slow?
-```
+## Query-plan debugging
 
 Preferred learning sequence:
 
@@ -214,13 +226,13 @@ show query/access pattern
 → inspect provider-native plan
 → identify scan/search/join evidence
 → developer proposes a change
-→ predict the changed plan
+→ predict changed plan
 → compare safely when a sandbox is available
 ```
 
-For SQLite, the V1 workbench uses `EXPLAIN QUERY PLAN` for `SELECT`/`WITH` queries when supplied parameters are sufficient. A learning session should connect `SCAN`/`SEARCH` behavior to concrete predicates, joins, ordering, and available indexes rather than simply recommending more indexes.
+Do not teach "add an index" without connecting it to a concrete access pattern, selectivity/order needs, write cost and plan evidence.
 
-## Example 5 — migration review
+## Migration review
 
 Prompt:
 
@@ -228,28 +240,28 @@ Prompt:
 /db-lab migration AddRecipeRatings
 ```
 
-The lab should show, when available:
+Connect:
 
 ```text
 migration intent
 ↔ migration/ORM operations
-↔ generated SQL/DDL
+↔ generated SQL/DDL when available
 ↔ schema before
 ↔ schema after
 ↔ data-safety concerns
 ```
 
-Useful questions include:
+Useful questions:
 
 - Is existing data compatible with a new non-null column?
 - Is a backfill required?
-- Does a new uniqueness constraint match the domain invariant?
-- Is a table rebuild or destructive operation involved?
+- Does a uniqueness constraint match the invariant?
+- Is a table rebuild/destructive operation involved?
 - What rollback limitations exist?
 
 Do not apply the migration in Database Lab mode.
 
-## Example 6 — database-design interview
+## Database-design interview
 
 Prompt:
 
@@ -257,46 +269,85 @@ Prompt:
 /db-lab interview database
 ```
 
-The interviewer should use the project domain for familiarity but change requirements so memorizing the existing schema does not solve the exercise.
+Use the project domain for familiarity but perturb requirements so memorizing the schema does not solve the exercise.
 
-Example follow-ups:
+Drive:
 
 ```text
-Why does this many-to-many relationship need an associative table?
-Could the two foreign keys be the primary key? What requirement would break that design?
-Which invariants belong in database constraints rather than application validation?
-What queries justify this index?
-What happens to historical records if the parent entity is deleted?
-How would this design change if multiple users edit the same aggregate concurrently?
+requirements
+→ entities
+→ relationships/cardinality
+→ keys/constraints
+→ normalization
+→ access patterns
+→ indexes/plans
+→ transactions/concurrency
+→ evolution/scaling
+→ design defense
 ```
 
-Use the standard L1-L6 learning levels, but assess database competencies independently. SQL syntax skill must not hide weak schema-design or indexing reasoning.
+Ask why a junction table exists, why a key was chosen, what deletion means historically, which query justifies an index, which invariant belongs in a database constraint, and what changes under concurrent edits.
 
 ## Database competency model
 
 ```text
-Relational modeling             entities, relationships, cardinality
-Keys + integrity                PK/FK/unique/check/nullability choices
-Normalization                   anomalies and deliberate denormalization
-SQL query construction          joins, aggregation, subqueries/CTEs, pagination
-Indexes + access patterns       index choices tied to real reads/writes
-Query plans                     evidence-based performance reasoning
-Transactions + concurrency      atomicity, isolation, conflict/failure behavior
-ORM translation                 what the abstraction generates/hides
-Schema evolution                migrations, compatibility, data safety
-Debugging                       symptom → evidence → cause
-Design defense                  tradeoffs and interview follow-up
+relational modeling
+keys + integrity constraints
+normalization + data anomalies
+SQL query construction
+indexes + access patterns
+query plans + performance reasoning
+transactions + concurrency
+ORM translation + abstraction leaks
+schema evolution + migrations
+database debugging
+design defense + interview communication
 ```
 
-A developer can be at different levels in each competency. Do not report one undifferentiated "SQL score".
+Use L1-L6 per competency rather than one undifferentiated SQL score.
+
+## Cross-lab learning
+
+System Lab owns system context; Database Lab owns database depth.
+
+```text
+/system-lab runtime checkout
+→ identify Orders DB
+→ /db-lab trace <order query>
+
+/db-lab plan <query>
+→ database evidence looks healthy but end-to-end latency is high
+→ /system-lab performance checkout
+```
+
+## Delivery-completion visibility
+
+Successful delivery may visibly recommend:
+
+```text
+★ /db-lab changes WI-24
+  This work changed database structure or behavior.
+  Explore affected relationships, queries, indexes, constraints, and ORM behavior.
+```
+
+When database-specific evidence was not materially touched, `/db-lab` may still appear as an available option:
+
+```text
+○ /db-lab
+  Explore the current database schema, relationships, queries, indexes, and ORM behavior.
+```
+
+Do not tell the learner to rebuild or refresh a diagram. Current evidence is part of invoking the lab.
+
+After successful merge/default-branch CI, `/deliver` may prepare a disposable SQLite workbench automatically only when the accepted change is DB-relevant, the tool exists, and a safe local development/test SQLite database path is already known. Never guess the path, create/apply migrations, mutate data, or touch Production just to prepare learning output. Failure remains non-blocking.
 
 ## Provider / ORM architecture
 
-The workbench stays provider/ORM-adapter oriented rather than becoming Family Meal Planner-specific.
+The workbench stays provider/ORM-adapter oriented rather than application-specific.
 
 ```text
 Database adapter
-  SQLite V1
+  SQLite concrete path
   PostgreSQL / SQL Server / ... future
 
 ORM evidence
@@ -319,13 +370,13 @@ Interactive viewer
   query-to-ERD highlighting
 ```
 
-SQLite + EF Core is the first concrete learning path, not a permanent architectural restriction.
+SQLite + EF Core is a first concrete learning path, not a permanent architectural restriction.
 
 ## IDE tooling
 
 Database extensions can improve the human exploration loop, but `/db-lab` must not depend on manipulating their UI.
 
-For SQLite projects, Bootstrap may recommend SQLTools plus its SQLite driver so the developer can independently browse/query the same local database. The reusable skill and workbench still obtain their authoritative evidence from repository/framework/provider-supported mechanisms.
+For SQLite projects, Bootstrap may recommend SQLTools plus its SQLite driver so the developer can independently browse/query the same local database. The reusable lab obtains authoritative evidence from repository/framework/provider-supported mechanisms.
 
 ## Safety and fallbacks
 
@@ -334,13 +385,13 @@ Database Lab is read-only learning by default.
 Do not:
 
 - connect to Production for learning exercises;
-- mutate real application data;
+- mutate application data;
 - apply/revert migrations;
 - create/drop indexes;
 - change code to prove a point;
 - claim an index was used without plan evidence;
 - manufacture executed SQL when only ORM source is available.
 
-The SQLite V1 workbench opens the database with SQLite `mode=ro`. Generated HTML/JSON are disposable learning artifacts and should normally go to a temp directory rather than tracked project paths.
+The SQLite workbench opens the database with SQLite `mode=ro`. Generated HTML/JSON are disposable learning artifacts and should normally go to temp/cache rather than tracked project paths.
 
-If evidence is missing, say so and continue with the strongest safe layer available. A missing database runtime, ORM trace, or interactive viewer should degrade the experience; it should not block learning or engineering delivery.
+If evidence is missing, say so and continue with the strongest safe layer available. A missing database runtime, ORM trace, interactive viewer, or post-delivery artifact should degrade the experience; it should never block learning or engineering delivery.