@mriekki/lean 0.4.3 → 0.4.5

package/assets/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@mriekki/lean",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "defaultProfile": "greenfield-poc",
   "profiles": {
     "greenfield-poc": {
@@ -14,7 +14,7 @@
   "components": {
     "core": {
       "repository": "mriekki/lean-agentic-core",
-      "commit": "1420caf15d5c078af8800f35966b47836b6da99f",
+      "commit": "68f3f45e663cab535c5a9544cf4efe2f048f8f34",
       "version": "1.13.0",
       "distribution": "greenfield-workspace",
       "descriptor": "assets/core/distribution.json",
@@ -23,7 +23,7 @@
     },
     "deployment": {
       "repository": "mriekki/lean-poc-deployment-kit",
-      "commit": "2763e604c20e64720d7de71fa93a88d99677be36",
+      "commit": "bfe07aac1809d4cf41428fba9fdbcfe6a5e85470",
       "distribution": "greenfield-poc",
       "descriptor": "assets/deployment/distribution.json",
       "sourceRoot": "assets/generated/deployment",

package/assets/core/distribution.json

@@ -25,6 +25,8 @@
     {"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/docs/SKILL.md","destination":".github/skills/docs/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,11 +37,15 @@
     {"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/PROJECT_DOCUMENTATION_FRAMEWORK.md","destination":"docs/process/PROJECT_DOCUMENTATION_FRAMEWORK.md"},
+    {"source":"core/process/LEAN_ENGINEERING_GUIDE.md","destination":"docs/lean/LEAN_ENGINEERING_GUIDE.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"},
     {"source":"core/templates/FEATURE_BRIEF_TEMPLATE.md","destination":"docs/templates/FEATURE_BRIEF_TEMPLATE.md"},
     {"source":"core/templates/REQUIREMENTS_TEMPLATE.md","destination":"docs/templates/REQUIREMENTS_TEMPLATE.md"},
+    {"source":"core/templates/ADR_TEMPLATE.md","destination":"docs/templates/ADR_TEMPLATE.md"},
     {"source":"core/learning/ENGINEERING_LEARNING_WORKBOOK.md","destination":"learning/ENGINEERING_LEARNING_WORKBOOK.md"},
     {"source":"core/learning/LEARNING_MAP.md","destination":"learning/LEARNING_MAP.md"},
     {"source":"core/learning/LEARNING_PROGRESS.md","destination":"learning/LEARNING_PROGRESS.md"},
@@ -49,6 +55,8 @@
     {"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/docs_site/docs_site.py","destination":"tools/lean-docs/docs-site.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/deployment/distribution.json

@@ -9,6 +9,8 @@
     {"source": "src/lean_poc_deployment/app_cli.py", "destination": "tools/lean-deployment/lean_poc_deployment/app_cli.py"},
     {"source": "src/lean_poc_deployment/app_runtime.py", "destination": "tools/lean-deployment/lean_poc_deployment/app_runtime.py"},
     {"source": "src/lean_poc_deployment/app_runtime_remote.py", "destination": "tools/lean-deployment/lean_poc_deployment/app_runtime_remote.py"},
+    {"source": "src/lean_poc_deployment/local_cli.py", "destination": "tools/lean-deployment/lean_poc_deployment/local_cli.py"},
+    {"source": "src/lean_poc_deployment/local_runtime.py", "destination": "tools/lean-deployment/lean_poc_deployment/local_runtime.py"},
     {"source": "src/lean_poc_deployment/box_platform.py", "destination": "tools/lean-deployment/lean_poc_deployment/box_platform.py"},
     {"source": "src/lean_poc_deployment/box_platform_assets.py", "destination": "tools/lean-deployment/lean_poc_deployment/box_platform_assets.py"},
     {"source": "src/lean_poc_deployment/box_platform_remote.py", "destination": "tools/lean-deployment/lean_poc_deployment/box_platform_remote.py"},

package/assets/generated/ASSEMBLY.json

@@ -1,11 +1,11 @@
 {
   "schemaVersion": 1,
   "package": "@mriekki/lean",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "components": {
     "core": {
       "repository": "mriekki/lean-agentic-core",
-      "commit": "1420caf15d5c078af8800f35966b47836b6da99f",
+      "commit": "68f3f45e663cab535c5a9544cf4efe2f048f8f34",
       "version": "1.13.0",
       "distribution": "greenfield-workspace",
       "files": [
@@ -27,12 +27,12 @@
         {
           "source": "core/instructions/lean-workflow.instructions.md",
           "destination": ".github/instructions/lean-workflow.instructions.md",
-          "sha256": "398b4734db1af4139e8395fc30dddd3fd45aaa76b4f5c5ce9c4b286c456d9430"
+          "sha256": "5f82d6709ad5382235bc83efdfdb031d1b97ff1050fa476db81c7753c8140054"
         },
         {
           "source": "core/instructions/lean-docs.instructions.md",
           "destination": ".github/instructions/lean-docs.instructions.md",
-          "sha256": "9d2d596fb9fc6c6f8afcc68ca6e4c94b2c50b396f3d970ef26797ae51cb03202"
+          "sha256": "f8b73ec5ae1e12fdd98db4ee2c404b0b770e78248bfadc827d00eefda4d5eaf5"
         },
         {
           "source": "core/skills/define-feature/SKILL.md",
@@ -62,12 +62,12 @@
         {
           "source": "core/skills/next-step/SKILL.md",
           "destination": ".github/skills/next-step/SKILL.md",
-          "sha256": "6fb5275cc098f3124c85bb20ccf713affac23ebd5b96962558504936f2b891d4"
+          "sha256": "94a7b7c0ec56a1772439dd0fc9b7adec1d48a67978c2bce5ab0cbe88d7ef74f0"
         },
         {
           "source": "core/skills/deliver/SKILL.md",
           "destination": ".github/skills/deliver/SKILL.md",
-          "sha256": "2c97f86bedf4baf1fb287cdc7b509975bd556861e9739713db85f1c5ee87c6eb"
+          "sha256": "5fe9875fb32a1e63a181342556f975522bf3a1e29d399567d905c51a83fa2750"
         },
         {
           "source": "core/skills/cleanup-branches/SKILL.md",
@@ -102,27 +102,37 @@
         {
           "source": "core/skills/deployment-readiness/SKILL.md",
           "destination": ".github/skills/deployment-readiness/SKILL.md",
-          "sha256": "02a58ae52cab8b6b11734a8d4217bf7f7c9b11bcd7b35e4a2e16dfb8af8bce34"
+          "sha256": "411fa4c918715679afc8636bd0e6503c1427688af213bd37cea4ba4920a678db"
         },
         {
           "source": "core/skills/deploy/SKILL.md",
           "destination": ".github/skills/deploy/SKILL.md",
-          "sha256": "259c0091672d79b7bc799f92cb21a4143af2951a4f2556794263237dfb7e7d7b"
+          "sha256": "3a118753fba9f3e529062b98adfba4df5e76842027421a75f4beeac9d6bc247b"
         },
         {
           "source": "core/skills/tear-down/SKILL.md",
           "destination": ".github/skills/tear-down/SKILL.md",
-          "sha256": "8826be8f97c5dab673c050c5ae7f959c5959871c401b0b3b7e6869660e669d93"
+          "sha256": "ac9dca37648dbd7ee1fa3b7117d136628cce5f8293a2c15d64f2ebcb8e788692"
         },
         {
           "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/docs/SKILL.md",
+          "destination": ".github/skills/docs/SKILL.md",
+          "sha256": "6edc48f28394ca99ea0e2a2abfa46901896199717a7a6b071028a43e56f327b7"
         },
         {
           "source": "core/skills/code-walkthrough/SKILL.md",
@@ -147,7 +157,7 @@
         {
           "source": "core/process/DEPLOYMENT_ENABLEMENT.md",
           "destination": "docs/process/DEPLOYMENT_ENABLEMENT.md",
-          "sha256": "3b59c5984ecb51ac48efb40e7e2e24c1971db947d6eefa5dc3671254ca984af7"
+          "sha256": "987f6e68a2ab58d23388127fae2318b385ef86de389fc616c1e40b48c0ff3b07"
         },
         {
           "source": "core/process/HUMAN_GATES.md",
@@ -167,12 +177,27 @@
         {
           "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/PROJECT_DOCUMENTATION_FRAMEWORK.md",
+          "destination": "docs/process/PROJECT_DOCUMENTATION_FRAMEWORK.md",
+          "sha256": "e6697c8d9bc346e8c8229625fc422b869a6428a083e4fee717b97d17afde7b03"
+        },
+        {
+          "source": "core/process/LEAN_ENGINEERING_GUIDE.md",
+          "destination": "docs/lean/LEAN_ENGINEERING_GUIDE.md",
+          "sha256": "85e18e8c00bfab8e05e9e5dbea0a74238b345d08634cf459ae2c3efe455e311a"
         },
         {
           "source": "core/process/SETUP_ACCEPTANCE_CHECKLIST.md",
@@ -199,20 +224,25 @@
           "destination": "docs/templates/REQUIREMENTS_TEMPLATE.md",
           "sha256": "ec85cc723071edb01f09acca41e20e9833afe21d06d103b39dfcdbfb59a31aed"
         },
+        {
+          "source": "core/templates/ADR_TEMPLATE.md",
+          "destination": "docs/templates/ADR_TEMPLATE.md",
+          "sha256": "f802ae066438642de9a4948980a4ab48c4cb68309fa5de16d48b08415a1a31fb"
+        },
         {
           "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 +257,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 +274,16 @@
           "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/docs_site/docs_site.py",
+          "destination": "tools/lean-docs/docs-site.py",
+          "sha256": "d8516175150b48b85b2a0b8013d5790b78bdd6eb6de73ab8dce9ed8e32e2dc68"
+        },
         {
           "source": "tools/package/check_baseline.py",
           "destination": "tools/lean-core/check-core-baseline.py",
@@ -258,7 +298,7 @@
     },
     "deployment": {
       "repository": "mriekki/lean-poc-deployment-kit",
-      "commit": "2763e604c20e64720d7de71fa93a88d99677be36",
+      "commit": "bfe07aac1809d4cf41428fba9fdbcfe6a5e85470",
       "distribution": "greenfield-poc",
       "files": [
         {
@@ -291,6 +331,16 @@
           "destination": "tools/lean-deployment/lean_poc_deployment/app_runtime_remote.py",
           "sha256": "f3ccde6ed3c6e5fe185a9a0f032a5c924fa0906e3619e12d0ad6228c1210f8ec"
         },
+        {
+          "source": "src/lean_poc_deployment/local_cli.py",
+          "destination": "tools/lean-deployment/lean_poc_deployment/local_cli.py",
+          "sha256": "9c658c0409da3c6297ad349035bccb263a587cd6d9b07a9796ccbb7cdb6676f9"
+        },
+        {
+          "source": "src/lean_poc_deployment/local_runtime.py",
+          "destination": "tools/lean-deployment/lean_poc_deployment/local_runtime.py",
+          "sha256": "82cf795733b59f4591515396be65317da4e515fde19874e3c5851bcff412d84d"
+        },
         {
           "source": "src/lean_poc_deployment/box_platform.py",
           "destination": "tools/lean-deployment/lean_poc_deployment/box_platform.py",
@@ -319,7 +369,7 @@
         {
           "source": "src/lean_poc_deployment/entrypoint.py",
           "destination": "tools/lean-deployment/lean_poc_deployment/entrypoint.py",
-          "sha256": "5161aec6d5a1fc684894a1011b3d577868cedaa7039ea647862a4628067fabd8"
+          "sha256": "8275c22ad1f9e3420630e773039902136ab036882f924b68f10ae5f602cae739"
         },
         {
           "source": "src/lean_poc_deployment/errors.py",
@@ -389,12 +439,12 @@
         {
           "source": "src/lean_poc_deployment/teardown.py",
           "destination": "tools/lean-deployment/lean_poc_deployment/teardown.py",
-          "sha256": "edcf921aa92988176b756abf4bbc9b0b83ae1d855b6e8d487b67aaad7727cb55"
+          "sha256": "114b6e29725caaf105e67b5407de9a21c4ae9a9bfdc965bd4a0f1e91c316d011"
         },
         {
           "source": "src/lean_poc_deployment/teardown_cli.py",
           "destination": "tools/lean-deployment/lean_poc_deployment/teardown_cli.py",
-          "sha256": "ec1271db5f57135189892e87f2df3ffc5fcb6e763ff1eb9604bc4e50788c3325"
+          "sha256": "93abb9350f1b06b0d53b38dff47030ecec982aed2455e9ddc4be12d70bfb6c3f"
         },
         {
           "source": "src/lean_poc_deployment/teardown_remote.py",

package/assets/generated/core/core/instructions/lean-docs.instructions.md

@@ -4,11 +4,42 @@ applyTo: "**/*.md"
 
 # Lean Documentation Rules
 
-Respect `.github/lean-workspace.json` and existing repository documentation.
+Respect `.github/lean-workspace.json`, `docs/lean-docs.json` when present, and existing repository documentation.
+
+## Authority
 
 - Do not create Product/Feature Briefs when the profile says they are unused.
 - Do not create duplicate requirement authorities.
+- `PROJECT_BRIEF.md` is a project briefing/navigation surface unless the repository explicitly says otherwise; do not let it silently compete with the accepted product/work-item authority.
 - Label experimental/supplemental briefs clearly.
 - Do not assume a Jira Epic is a Feature Brief.
 - Prefer one useful combined requirements artifact over a conveyor belt of docs when local requirements are appropriate.
-- Keep secret values out of tracked Markdown.
+
+## Ownership
+
+When `docs/lean-docs.json` is present, preserve its ownership boundary:
+
+- `project` — project-owned prose/decisions; update only when the current change actually owns that documentation.
+- `lean` — reusable Lean-managed material; update through the controlled reusable-package/baseline path rather than hand-diverging it in consumers.
+- `generated-evidence` — disposable projections reconstructed from current evidence; do not hand-edit or treat them as requirements.
+
+ADRs are project-owned decisions. Do not create or approve an architectural decision on the human's behalf merely because implementation evidence suggests one.
+
+## Generated views
+
+- Markdown is canonical; the local documentation website is a projection.
+- DB/System diagrams are current-by-default projections. Do not tell the developer to maintain, rebuild, or manually synchronize generated diagrams.
+- Keep disposable site/lab output under `.lean/` or another repository-approved ignored cache path by default.
+- A generated view may report `CURRENT`, `STALE`, `AVAILABLE / FRESHNESS UNKNOWN`, or `NOT GENERATED`; do not claim freshness without supporting evidence.
+- Repository/runtime/database evidence outranks stale generated views.
+
+## Change impact
+
+When a change materially affects public contracts, architecture, persistence, deployment/environments, developer workflow, testing strategy, or an architectural tradeoff, surface the likely documentation impact. Safe generated projections may be rebuilt automatically; human/project-authored prose should not be silently rewritten merely because code changed.
+
+Documentation follow-up is non-blocking unless the work item's acceptance criteria explicitly require documentation.
+
+## Safety
+
+- Keep sensitive values out of tracked Markdown, documentation manifests, and generated site data.
+- Preserve evidence labels and uncertainty rather than turning inference into authoritative architecture facts.

package/assets/generated/core/core/instructions/lean-workflow.instructions.md

@@ -34,4 +34,46 @@ After implementation review and local human acceptance, manually invoking `/deli
 
 Changed PR evidence re-opens the relevant review gate. Merge never implies production-deployment authorization.
 
+## Post-delivery documentation and learning handoff
+
+After engineering delivery is complete, documentation impact and learning are **non-blocking follow-ups**, not new delivery states or gates.
+
+Use the accepted work-item/PR diff conservatively to classify likely documentation impact. Examples:
+
+- public API/contract changes may affect architecture/runtime/API narrative;
+- services, dependencies, messaging, caches, auth, observability, deployment topology, or failure handling may affect System evidence;
+- entities, migrations, schema/DDL, ORM, queries, constraints, or indexes may affect DB evidence;
+- environment/deployment changes may affect operations docs;
+- durable developer/test workflow changes may affect engineering docs;
+- a consequential architectural tradeoff may deserve an ADR recommendation.
+
+A changed file proves relevant evidence was touched; it does not by itself prove a runtime or physical-schema change.
+
+When the relevant tools exist and prerequisites are safe, `/deliver` may best-effort prepare **disposable** evidence/site projections under:
+
+```text
+.lean/docs-cache/system/
+.lean/docs-cache/database/
+.lean/docs-site/
+```
+
+System evidence may be reconstructed from the current repository. Database evidence may be generated automatically only when a safe local development/test database path is already explicit; never guess a path merely to populate docs.
+
+If `tools/lean-docs/docs-site.py` exists, a build of the local documentation projection may follow safe lab preparation. Failure to build docs or a lab projection does not change `DELIVERY COMPLETE`.
+
+Do not silently rewrite project-owned narrative or approve/create an ADR solely because implementation evidence changed. Instead surface a compact `DOCUMENTATION IMPACT` handoff, for example:
+
+```text
+DOCUMENTATION IMPACT
+
+✓ Project brief: no material change detected
+★ System evidence: changed; current projection prepared
+★ Database evidence: changed; /db-lab recommended
+○ ADR consideration: new synchronous external dependency introduced
+
+/docs — explore the current project documentation
+```
+
+Use only claims supported by observed evidence. Keep `/docs`, `/db-lab`, `/system-lab`, `/code-walkthrough`, and `/learning-review` visible when useful, but never require them solely to complete engineering delivery.
+
 Do not pin or automatically escalate models.

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.