@mriekki/lean 0.4.3 → 0.4.4

package/assets/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@mriekki/lean",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "defaultProfile": "greenfield-poc",
   "profiles": {
     "greenfield-poc": {
@@ -14,7 +14,7 @@
   "components": {
     "core": {
       "repository": "mriekki/lean-agentic-core",
-      "commit": "1420caf15d5c078af8800f35966b47836b6da99f",
+      "commit": "c2d9538cdbb5ddb46527133fefae698e25a6e603",
       "version": "1.13.0",
       "distribution": "greenfield-workspace",
       "descriptor": "assets/core/distribution.json",

package/assets/core/distribution.json

@@ -25,6 +25,7 @@
     {"source":"core/skills/tear-down/SKILL.md","destination":".github/skills/tear-down/SKILL.md"},
     {"source":"core/skills/coach/SKILL.md","destination":".github/skills/coach/SKILL.md"},
     {"source":"core/skills/db-lab/SKILL.md","destination":".github/skills/db-lab/SKILL.md"},
+    {"source":"core/skills/system-lab/SKILL.md","destination":".github/skills/system-lab/SKILL.md"},
     {"source":"core/skills/code-walkthrough/SKILL.md","destination":".github/skills/code-walkthrough/SKILL.md"},
     {"source":"core/skills/learning-review/SKILL.md","destination":".github/skills/learning-review/SKILL.md"},
     {"source":"core/process/WORK_ITEM_MODEL.md","destination":"docs/process/WORK_ITEM_MODEL.md"},
@@ -35,6 +36,7 @@
     {"source":"core/process/INTERACTIVE_SESSION_GUIDE.md","destination":"docs/process/INTERACTIVE_SESSION_GUIDE.md"},
     {"source":"core/process/COACHING_GUIDE.md","destination":"docs/process/COACHING_GUIDE.md"},
     {"source":"core/process/DATABASE_LEARNING_WORKBENCH.md","destination":"docs/process/DATABASE_LEARNING_WORKBENCH.md"},
+    {"source":"core/process/SYSTEM_DESIGN_LEARNING_WORKBENCH.md","destination":"docs/process/SYSTEM_DESIGN_LEARNING_WORKBENCH.md"},
     {"source":"core/process/SETUP_ACCEPTANCE_CHECKLIST.md","destination":"docs/process/SETUP_ACCEPTANCE_CHECKLIST.md"},
     {"source":"core/templates/PULL_REQUEST_TEMPLATE.md","destination":".github/PULL_REQUEST_TEMPLATE.md"},
     {"source":"core/templates/PRODUCT_BRIEF_TEMPLATE.md","destination":"docs/templates/PRODUCT_BRIEF_TEMPLATE.md"},
@@ -49,6 +51,7 @@
     {"source":"core/learning/DIAGRAM_GUIDE.md","destination":"learning/DIAGRAM_GUIDE.md"},
     {"source":"core/learning/RESOURCE_CATALOG.md","destination":"learning/RESOURCE_CATALOG.md"},
     {"source":"tools/db_lab/sqlite_workbench.py","destination":"tools/lean-db-lab/sqlite-workbench.py"},
+    {"source":"tools/system_lab/system_workbench.py","destination":"tools/lean-system-lab/system-workbench.py"},
     {"source":"tools/package/check_baseline.py","destination":"tools/lean-core/check-core-baseline.py"},
     {"source":"tools/package/check_upstream.py","destination":"tools/lean-core/check-core-upstream.py"}
   ]

package/assets/generated/ASSEMBLY.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
   "package": "@mriekki/lean",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "components": {
     "core": {
       "repository": "mriekki/lean-agentic-core",
-      "commit": "1420caf15d5c078af8800f35966b47836b6da99f",
+      "commit": "c2d9538cdbb5ddb46527133fefae698e25a6e603",
       "version": "1.13.0",
       "distribution": "greenfield-workspace",
       "files": [
@@ -62,12 +62,12 @@
         {
           "source": "core/skills/next-step/SKILL.md",
           "destination": ".github/skills/next-step/SKILL.md",
-          "sha256": "6fb5275cc098f3124c85bb20ccf713affac23ebd5b96962558504936f2b891d4"
+          "sha256": "833b015a795dee2fa8eaefd8b7ea7dda42951390846cf3bc8c2c2eb2ea3451bf"
         },
         {
           "source": "core/skills/deliver/SKILL.md",
           "destination": ".github/skills/deliver/SKILL.md",
-          "sha256": "2c97f86bedf4baf1fb287cdc7b509975bd556861e9739713db85f1c5ee87c6eb"
+          "sha256": "5fe9875fb32a1e63a181342556f975522bf3a1e29d399567d905c51a83fa2750"
         },
         {
           "source": "core/skills/cleanup-branches/SKILL.md",
@@ -117,12 +117,17 @@
         {
           "source": "core/skills/coach/SKILL.md",
           "destination": ".github/skills/coach/SKILL.md",
-          "sha256": "9a15c5876b6dcaaa5157c65c28f797302bd3f869048261f0d070904713b239e7"
+          "sha256": "68c28d5b9a55eedbf4261d12f1cd06f86b905e973b7ed7973fa4c49cf5338091"
         },
         {
           "source": "core/skills/db-lab/SKILL.md",
           "destination": ".github/skills/db-lab/SKILL.md",
-          "sha256": "6c7868002b7408215e20807a427213b1d5a15473379c91396e8757a50a1be947"
+          "sha256": "1ad8ec01411abcd576f9486a9a1aab83c844d27eaa8f70d1001676d2047e2c67"
+        },
+        {
+          "source": "core/skills/system-lab/SKILL.md",
+          "destination": ".github/skills/system-lab/SKILL.md",
+          "sha256": "1ec8c3f46cca6e2e72be1a85aae1adad0c32872e531d80baf12b1e49f2b780fc"
         },
         {
           "source": "core/skills/code-walkthrough/SKILL.md",
@@ -167,12 +172,17 @@
         {
           "source": "core/process/COACHING_GUIDE.md",
           "destination": "docs/process/COACHING_GUIDE.md",
-          "sha256": "afe5d77028768d5a2d47cad94dc3436f368b94c22d87fe9a36fa0fdcaa5c461f"
+          "sha256": "cf141525e71467b189b18283ba8616859c665bba632f92de80e94f2de2e8f7b4"
         },
         {
           "source": "core/process/DATABASE_LEARNING_WORKBENCH.md",
           "destination": "docs/process/DATABASE_LEARNING_WORKBENCH.md",
-          "sha256": "8db2008cce0fd1b63aea27c1e47ab2c96ad380a2f80cc9be1743c3961d86d0a7"
+          "sha256": "282566eca21d777614810d37403c0093efff4cee7f561874e5b0482ebd27d4fb"
+        },
+        {
+          "source": "core/process/SYSTEM_DESIGN_LEARNING_WORKBENCH.md",
+          "destination": "docs/process/SYSTEM_DESIGN_LEARNING_WORKBENCH.md",
+          "sha256": "eb0f613717d6bfdaecbb9d3a8ecb6323fa27331e429f5c5781c5c5a0289a8091"
         },
         {
           "source": "core/process/SETUP_ACCEPTANCE_CHECKLIST.md",
@@ -202,17 +212,17 @@
         {
           "source": "core/learning/ENGINEERING_LEARNING_WORKBOOK.md",
           "destination": "learning/ENGINEERING_LEARNING_WORKBOOK.md",
-          "sha256": "e46909fe4b88cf1b617b9eb1f9b8cd1d78b9332e9c8825bd6e6021aadcd99552"
+          "sha256": "e065342b6a5fb8a5f39ec616c1f59b7417cf3cba4238d01b0fee6d23ba881af6"
         },
         {
           "source": "core/learning/LEARNING_MAP.md",
           "destination": "learning/LEARNING_MAP.md",
-          "sha256": "172385b97c4fd41c08bc5344e29d026e48950b7bf98e9225288ab254b51ea9e0"
+          "sha256": "c1e3b565b57fa0cced6a0a1abe66cbbe67c7cd4960ff9c0307564cf1e2c76470"
         },
         {
           "source": "core/learning/LEARNING_PROGRESS.md",
           "destination": "learning/LEARNING_PROGRESS.md",
-          "sha256": "c47e5ff009a789046998d67dae1d67dfca8a7ada2f963362747faea0edb11e1e"
+          "sha256": "50a19d3d3c7da4c2082ab7f5832c1ed5f90b54495db6c4aced3cb3a07ad78f89"
         },
         {
           "source": "core/learning/CODING_DRILLS.md",
@@ -227,12 +237,12 @@
         {
           "source": "core/learning/SYSTEM_DESIGN_DRILLS.md",
           "destination": "learning/SYSTEM_DESIGN_DRILLS.md",
-          "sha256": "4d197fe4bf2f618dcc212db304fd18f450ed3955fdce4ac2722371ee52b12a58"
+          "sha256": "1fbcd5b0cebfb1fa0ba3051cb019ef110790190b06e034075a37109711963154"
         },
         {
           "source": "core/learning/DIAGRAM_GUIDE.md",
           "destination": "learning/DIAGRAM_GUIDE.md",
-          "sha256": "c4626c30f3d0f8212b9a8b0d3e4f2ead4ff067bc4e015e801d8c35b00838e365"
+          "sha256": "a2c9a3475dca76f2192b0ad2250ae20731c6ab213204b364e2305e37bf867e84"
         },
         {
           "source": "core/learning/RESOURCE_CATALOG.md",
@@ -244,6 +254,11 @@
           "destination": "tools/lean-db-lab/sqlite-workbench.py",
           "sha256": "a5bb99a3f67f88f00b99c10b2c0698710b6b2fa302becc6ff3435c4321cdd4d3"
         },
+        {
+          "source": "tools/system_lab/system_workbench.py",
+          "destination": "tools/lean-system-lab/system-workbench.py",
+          "sha256": "25b507bacb05b938bee299bcb44a5476a6fc5ecb9143f5561773adc7ff987fcc"
+        },
         {
           "source": "tools/package/check_baseline.py",
           "destination": "tools/lean-core/check-core-baseline.py",

package/assets/generated/core/core/learning/DIAGRAM_GUIDE.md

@@ -1,6 +1,12 @@
 # Diagram Guide
 
-Coach may use Mermaid diagrams in chat for:
+Diagrams are learning views, not architecture authorities.
+
+Use current repository/runtime/database evidence first. Generated diagrams are disposable projections and should normally be regenerated from current evidence when the relevant lab is invoked rather than manually maintained.
+
+## Lightweight diagrams
+
+Coach may use ephemeral Mermaid/text diagrams in chat for:
 
 - architecture,
 - request flow,
@@ -9,11 +15,45 @@ Coach may use Mermaid diagrams in chat for:
 - ER/data relationships,
 - CI/CD,
 - deployment,
-- concurrency.
+- concurrency,
+- messaging timelines,
+- failure propagation.
+
+Only save them as durable project artifacts when explicitly requested.
+
+## Interactive diagrams
+
+Prefer `/db-lab` when the learning question needs schema/query/index/ORM/plan evidence. Prefer `/system-lab` when it needs architecture/runtime/API/dependency/failure/scale/observability/security/deployment evidence.
+
+Interactive views should support learning, not merely look attractive. Useful interactions include:
+
+- select a scenario and highlight participating nodes/edges;
+- click a component/table/dependency for evidence and responsibilities;
+- show query/index/plan relationships;
+- show work-item change overlays;
+- show failure or scale perturbations;
+- link system database nodes to `/db-lab` depth;
+- distinguish current evidence from inferred topology.
+
+## Evidence provenance
+
+Use explicit labels where ambiguity matters:
+
+```text
+CONFIRMED BY CODE
+CONFIRMED BY RUNTIME
+DOCUMENTED INTENT
+INFERRED
+UNKNOWN
+LEARNER ASSUMPTION
+```
+
+A static dependency edge is not automatically proof that the call occurred at runtime. A generated ERD is not more authoritative than the physical database metadata from which it was generated.
+
+## Learning behavior
 
-Diagrams are ephemeral by default.
+After a diagram, ask the developer to explain the relevant flow, state, failure path, boundary, scaling concern, or tradeoff.
 
-Only save them when explicitly requested.
+For advanced exercises, ask the learner to predict a failure/plan/scale consequence before revealing the overlay when useful.
 
-After a diagram, ask the developer to explain the flow, failure path, boundary,
-and tradeoff.
+Never require the human to "refresh" or "rebuild" a learning diagram as routine maintenance. Running the lab means inspect current evidence and create/show the current view.

package/assets/generated/core/core/learning/ENGINEERING_LEARNING_WORKBOOK.md

@@ -12,12 +12,13 @@ Use the learning tools for different purposes:
 /code-walkthrough — instructional walkthrough of actual implementation changes
 /learning-review   — assessment of whether the developer can explain and defend the implementation
 /coach             — targeted concept learning, debugging practice, design discussion, drills, and deeper follow-up
-/db-lab            — evidence-backed database/schema/ORM/query-plan exploration and database interview practice
+/db-lab            — evidence-backed database/schema/ORM/query-plan/change exploration and database interview practice
+/system-lab        — evidence-backed architecture/runtime/failure/scale/change exploration and system-design interview practice
 ```
 
 All learning activity is optional and never an engineering delivery gate.
 
-For database usage examples, see `docs/process/DATABASE_LEARNING_WORKBENCH.md` in a greenfield consumer.
+For database usage examples, see `docs/process/DATABASE_LEARNING_WORKBENCH.md` in a greenfield consumer. For advanced system-design usage, see `docs/process/SYSTEM_DESIGN_LEARNING_WORKBENCH.md`.
 
 ## Preferred project-first sequence
 
@@ -27,9 +28,11 @@ When an implementation is stable enough to study, a useful optional sequence is:
 implementation
 → /code-walkthrough
 → /learning-review
-→ targeted /coach or /db-lab follow-up where gaps remain
+→ targeted /coach, /db-lab, or /system-lab where gaps remain
 ```
 
+After successful delivery, the workflow may surface the relevant evidence labs again while the change is fresh. A work item that changed persistence may make `/db-lab changes <work-item>` especially useful; one that changed APIs, dependencies, messaging, runtime topology, security, observability, performance or failure behavior may make `/system-lab changes <work-item>` especially useful. These are recommendations, not gates.
+
 A code walkthrough should connect two views of every meaningful change:
 
 ```text
@@ -42,7 +45,26 @@ Which files, classes, functions, data structures, framework mechanisms, tests, a
 
 Then connect the files into an end-to-end flow such as request, data, state, event, persistence, UI, or operational behavior. Use the repository's actual architecture rather than forcing a generic sequence.
 
-During a walkthrough, deeper learning can branch into tracing, diagrams, debugging discussion, design tradeoffs, quizzes, or interview-style explanation. The walkthrough remains read-only; discovered implementation issues return to the normal engineering workflow rather than being silently fixed inside learning mode.
+During a walkthrough, deeper learning can branch into tracing, interactive diagrams, debugging discussion, design tradeoffs, quizzes, capacity/failure reasoning, or interview-style explanation. The walkthrough and labs remain read-only; discovered implementation issues return to the normal engineering workflow rather than being silently fixed inside learning mode.
+
+## Advanced learning pattern
+
+Evidence labs should favor active reasoning:
+
+```text
+current evidence
+→ learner prediction/assumption
+→ reveal strongest available evidence
+→ explain discrepancy
+→ trace/apply/debug
+→ defend tradeoff
+→ change one constraint
+→ reason again
+```
+
+Use explanation-first when the human asks for it. Do not turn every learning interaction into a quiz.
+
+Generated workbench diagrams are disposable projections. The repository/database/runtime evidence remains authoritative, and invoking a lab should rebuild its view from current evidence automatically.
 
 ## Suggested practice loop
 
@@ -67,9 +89,10 @@ concept or changed code
 - CI/CD/deployment/operations,
 - security and data protection,
 - architecture/system design,
+- capacity/performance/reliability,
 - coding/DSA interview patterns.
 
-Use `LEARNING_MAP.md` to choose a small number of high-value topics and the drill files for focused practice. Learning progress is optional and never an engineering gate.
+Use `LEARNING_MAP.md` to choose a small number of high-value topics and the drill files for focused practice. Database and system-design depth should be tracked by independent competencies rather than one broad score. Learning progress is optional and never an engineering gate.
 
 ## Experience credibility
 
@@ -82,4 +105,4 @@ studied/practiced
 not yet understood
 ```
 
-A code walkthrough can help move AI-assisted implementation toward reviewed/understood code, but it does not by itself prove mastery or professional experience. Learning must not become a false claim of professional experience.
+A code walkthrough or lab can help move AI-assisted implementation toward reviewed/understood code, but it does not by itself prove mastery or professional experience. Generated diagrams and completed exercises must not become false claims of professional experience.

package/assets/generated/core/core/learning/LEARNING_MAP.md

@@ -46,7 +46,38 @@ database debugging
 design defense / interview communication
 ```
 
-Use `/db-lab` for evidence-backed exploration of the current project's schema, queries, ORM translation, query plans, migrations, and query-to-ERD relationships. Use `/coach` for adaptive teaching and reinforcement.
+Use `/db-lab` for evidence-backed exploration of the current project's schema, queries, ORM translation, query plans, migrations, change impact, and query-to-ERD relationships. Invoking the lab means inspect current evidence; generated views are disposable rather than manually maintained diagrams. Use `/coach` for adaptive teaching and reinforcement.
+
+## System-design learning is multi-dimensional
+
+Do not reduce system design to one generic architecture score. Assess the relevant areas independently:
+
+```text
+requirements + scope framing
+capacity estimation + workload modeling
+API + contract design
+service/module decomposition
+data/storage selection
+caching
+messaging + asynchronous workflows
+consistency + distributed coordination
+scaling + partitioning
+availability + fault tolerance
+latency + performance
+runtime/deployment topology
+observability + SLO reasoning
+security + abuse resistance
+cost/complexity awareness
+architecture evolution
+incident/debug reasoning
+testing/verification strategy
+tradeoff defense
+interview communication
+```
+
+Use `/system-lab` for evidence-backed exploration of the current project's architecture, runtime/data/event flows, dependencies, failure behavior, capacity/performance, observability, security, messaging, deployment, testing, work-item architecture impact, evolution, and interview practice. Generated interactive diagrams are disposable projections of current evidence; they are not a second architecture authority and should be regenerated from current evidence when the lab is invoked.
+
+Use `/coach system design` for conceptual teaching, adaptive questions, and transfer practice. Prefer prediction-before-reveal for plans, failures, scale changes, consistency situations, and design perturbations when that improves learning.
 
 ## How real-code learning maps to the levels
 
@@ -68,6 +99,10 @@ L6 Interview Ready — explain the implementation clearly under follow-up questi
 
 For database work, L4-L6 should include evidence-based reasoning about schema choices, constraints, access patterns, indexes/plans, transactions, ORM behavior, migration safety, and credible alternatives where relevant.
 
-Use `/learning-review` to assess understanding after a walkthrough. Use `/coach` for targeted reinforcement, practice, or deeper exploration. These activities are optional and do not affect engineering delivery state.
+For system-design work, L4-L6 should include evidence-based reasoning about workload assumptions, boundaries, APIs/data flows, failure propagation, consistency, latency, scaling, reliability, observability, security, deployment, testing, cost/complexity, architecture evolution, and credible simpler alternatives.
+
+A learner can be L5 in API design and L2 in distributed consistency, or strong in SQL construction and weak in indexing. Preserve that shape instead of averaging it away.
+
+Use `/learning-review` to assess understanding after a walkthrough. Use `/coach` for targeted reinforcement, practice, or deeper exploration. Use `/db-lab` and `/system-lab` when concrete project evidence is the learning material. These activities are optional and do not affect engineering delivery state.
 
 Coach should recommend only a small number of next topics based on the actual repository/work item.

package/assets/generated/core/core/learning/LEARNING_PROGRESS.md

@@ -18,14 +18,22 @@ This file is optional and never an engineering gate.
 
 Record evidence only when the human explicitly chooses to update learning progress. Useful evidence can include:
 
-- completed `/code-walkthrough` of a real implementation change set,
-- explained the functional and technical purpose of important changed files,
-- traced a request/data/state/event path across the implementation,
-- explained a design choice and a credible alternative,
-- reasoned through a failure mode or debugging approach,
-- passed a `/learning-review` question at a demonstrated level,
+- completed `/code-walkthrough` of a real implementation change set;
+- explained the functional and technical purpose of important changed files;
+- traced a request/data/state/event path across the implementation;
+- explained a design choice and a credible alternative;
+- reasoned through a failure mode or debugging approach;
+- predicted then explained query-plan/index behavior using `/db-lab` evidence;
+- explained schema/ORM/migration consequences from `/db-lab changes <work-item>`;
+- traced an evidence-backed runtime/dependency path using `/system-lab`;
+- predicted failure propagation, bottlenecks, consistency behavior, or latency consequences and reconciled the prediction with evidence;
+- defended an architecture choice against a simpler credible alternative;
+- adapted a design after an interview-style scale/reliability/security constraint changed;
+- passed a `/learning-review` question at a demonstrated level;
 - completed a focused `/coach` exercise or drill.
 
-A walkthrough is evidence of review/understanding activity, not automatic proof of mastery. Record the demonstrated level conservatively.
+For database and system-design depth, prefer recording the demonstrated competency rather than one broad level. For example, capacity estimation, distributed consistency, API design, relational modeling and query-plan reasoning can legitimately be at different levels.
+
+A walkthrough, generated workbench, or completed lab invocation is evidence of learning/review activity, not automatic proof of mastery. Record demonstrated understanding conservatively.
 
 Do not update automatically.