@mriekki/lean 0.4.3 → 0.4.5

package/assets/generated/core/core/skills/docs/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: docs
+description: "Open or inspect the repository's current Lean project documentation site, ownership/authority map, and DB/System evidence freshness without creating a new workflow gate."
+argument-hint: "[open|check|build]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Project Docs
+
+`/docs` is the front door to repository documentation. It is read-only with respect to project prose unless the human explicitly asks to edit documentation.
+
+## Purpose
+
+Use `/docs` to:
+
+- open the local project documentation site;
+- inspect documentation ownership/authority;
+- find the correct product, architecture, engineering, operations, learning, or ADR document;
+- see whether disposable System/DB evidence views are current, stale, unknown, or absent;
+- keep `/db-lab` and `/system-lab` easy to discover.
+
+Markdown remains canonical. The site is a generated local projection.
+
+## Default behavior
+
+When invoked without a mode:
+
+1. Read `docs/lean-docs.json` when present.
+2. Verify the documentation viewer exists at `tools/lean-docs/docs-site.py`.
+3. If it exists, use the repository-local Python/runtime convention to run:
+
+```text
+python tools/lean-docs/docs-site.py serve --root .
+```
+
+The viewer binds to loopback only and writes disposable output under `.lean/`.
+
+If the tool is unavailable, do not invent installation support. Fall back to a concise documentation map from repository Markdown and mention that the local viewer is unavailable in the current accepted baseline.
+
+## Modes
+
+### `/docs open`
+
+Equivalent to the default behavior.
+
+### `/docs check`
+
+Do not open a browser. Inspect:
+
+- `docs/lean-docs.json` validity when present;
+- missing listed documents;
+- ownership/authority declarations;
+- current Git commit;
+- System Lab cache freshness when evidence exists;
+- DB Lab cache availability/freshness only when evidence supports a conclusion.
+
+Do not treat a missing optional Lean-managed document as project corruption when Bootstrap generation and reusable-package application are still distinct phases.
+
+### `/docs build`
+
+Generate the disposable site without serving it:
+
+```text
+python tools/lean-docs/docs-site.py build --root . --out .lean/docs-site
+```
+
+This is a local derived artifact and should not normally be committed.
+
+## Current-by-default evidence
+
+System Lab can reconstruct architecture from repository evidence. The docs viewer may best-effort prepare the current System Lab projection when it starts and the tool is present.
+
+Database Lab is stricter: do not guess a database path. Show an existing DB projection or hand off to `/db-lab`; automatic generation is allowed only when a safe local development/test database path is already explicit.
+
+Never create a database, apply migrations, mutate application data, or inspect Production merely to populate documentation.
+
+## Ownership
+
+Respect `docs/lean-docs.json`:
+
+- `project` — project-owned prose and ADRs;
+- `lean` — reusable managed reference/process material;
+- `generated-evidence` — disposable projections.
+
+Do not silently rewrite `project` documents during `/docs` just because code changed. Surface likely documentation impact instead.
+
+## ADR behavior
+
+If current evidence reveals a consequential architecture choice that lacks a durable decision record, `/docs` may recommend creating an ADR from `docs/templates/ADR_TEMPLATE.md`.
+
+Recommendation is not approval. Do not invent or accept the decision for the human.
+
+## Output when not opening the site
+
+Prefer a compact result such as:
+
+```text
+PROJECT DOCS
+
+Entry: PROJECT_BRIEF.md
+Product authority: docs/product/PRODUCT_BRIEF.md
+Work-item authority: docs/work-items/...
+Current commit: abc1234
+
+System evidence: CURRENT / STALE / NOT GENERATED
+Database evidence: CURRENT / STALE / AVAILABLE-FRESHNESS-UNKNOWN / NOT GENERATED
+
+Useful:
+- /system-lab
+- /db-lab
+- /code-walkthrough
+- /learning-review
+```
+
+Documentation status is not a delivery gate unless an approved work item explicitly requires documentation as acceptance evidence.

package/assets/generated/core/core/skills/next-step/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: next-step
-description: Read-only orientation over work-item, Git, review, PR, PR CI, merge, post-merge default-branch CI, deployment readiness, and deployment handoff state.
+description: Read-only orientation over work-item, Git, review, PR, PR CI, merge, post-merge default-branch CI, deployment readiness, deployment handoff state, and optional documentation/learning surfaces.
 argument-hint: "[optional work-item ID or external key]"
 user-invocable: true
 disable-model-invocation: true
@@ -68,7 +68,7 @@ Use only states supported by observed evidence.
 
 Do not add a separate final-PR-acceptance state when the PR still exactly matches the already accepted local implementation. In that normal case, `/deliver` combines final acceptance and merge into the single `MERGE_READY` decision. If PR evidence changed materially, describe the required final PR review explicitly before returning to `MERGE_READY`.
 
-Do not add learning-only states such as `CODE_WALKTHROUGH_PENDING`. Optional coaching does not change engineering delivery state.
+Do not add learning- or documentation-only states such as `CODE_WALKTHROUGH_PENDING` or `DOCS_UPDATE_PENDING`. Optional coaching, labs, and project documentation do not change engineering delivery state unless the approved work item explicitly makes documentation acceptance evidence.
 
 ## 3. Output
 
@@ -88,17 +88,30 @@ OPTIONS
 
 Only show relevant options. `/next-step` orients; it does not become another workflow database.
 
-## 4. Optional learning choices
+## 4. Optional documentation and learning choices
 
-When implementation is stable enough to learn from and the human appears interested in understanding the code, `/next-step` may offer learning choices without making them gates:
+When implementation is stable enough to understand or document, `/next-step` may offer these choices without making them gates:
 
 ```text
+/docs [open|check|build] — project documentation map/site and evidence freshness [READ ONLY]
 /code-walkthrough <scope> — guided changed-file explanation [READ ONLY]
 /learning-review <scope> — understanding assessment [READ ONLY]
 /coach <topic> — focused concept coaching [READ ONLY]
+/db-lab [changes <work-item>] — current database/schema/query/ORM evidence [READ ONLY]
+/system-lab [changes <work-item>] — current architecture/runtime/failure/design evidence [READ ONLY]
 ```
 
-Prefer `/code-walkthrough` when the user wants to understand what changed across an implementation. Do not recommend it as mandatory before `/deliver`.
+Prefer `/docs` when the user wants the coherent project briefing, documentation map, ADR/architecture/operations references, or current DB/System projection status. Prefer `/code-walkthrough` when the user wants to understand what changed across an implementation. Prefer `/db-lab` when the question depends on concrete schema/query/index/ORM evidence. Prefer `/system-lab` when it depends on architecture, runtime flows, APIs, dependencies, failure behavior, scale, messaging, observability, security, deployment, testing, or system-design tradeoffs.
+
+When a known work-item diff materially touches documentation-sensitive areas, make the impact visible without inventing a gate. Examples include public contracts, architecture/dependencies, persistence/schema, deployment/environments, developer workflow, test strategy, or a consequential architecture tradeoff that may deserve an ADR.
+
+Safe generated projections may be prepared automatically. Do not silently rewrite project-owned prose or accept an ADR on the human's behalf merely because implementation evidence changed.
+
+When a known work-item diff materially touches a DB/System evidence area, make the corresponding `changes <work-item>` option visibly relevant. Do not claim a runtime or physical-schema change solely because a file was touched.
+
+Labs inspect current evidence when invoked. Do not tell the human to refresh, rebuild, or manually synchronize a generated diagram.
+
+Do not recommend any documentation or learning activity as mandatory before `/deliver` unless the approved work item explicitly requires it.
 
 ## 5. Delivery handoff
 
@@ -140,7 +153,7 @@ Never merge from `/next-step` merely because CI is green.
 After merge:
 - if required default-branch CI is pending, return to `/deliver` to resume observation/finalization;
 - if failed, inspect/diagnose;
-- if green and branch finalization is safe/complete, report delivery complete.
+- if green and branch finalization is safe/complete, report delivery complete and optional relevant documentation/learning follow-ups without changing the delivery state.
 
 ## 6. Deployment handoff
 
@@ -173,3 +186,5 @@ Do not infer readiness of one environment from another. Production is never an i
 ## 7. Keep it lean
 
 Do not auto-run Reviewer, auto-run learning activities, auto-merge, auto-deploy, pin/select a model, or maintain duplicate workflow state outside Git/GitHub and the configured work-item/readiness authority.
+
+Generating a disposable read-only documentation or learning workbench is not the same as performing a learning activity, approving documentation prose, or proving understanding. `/deliver` may prepare such artifacts best-effort after successful delivery when safe and relevant; learning itself remains optional.

package/assets/generated/core/core/skills/system-lab/SKILL.md

@@ -0,0 +1,333 @@
+---
+name: system-lab
+description: "Optional evidence-backed advanced system-design lab for architecture, runtime flows, APIs, failures, capacity, performance, observability, security, messaging, deployment, testing, evolution, debugging, and interview practice."
+argument-hint: "[architecture|runtime|api|failure|capacity|performance|observability|security|messaging|deployment|testing|debug|changes|evolve|compare|interview|topic] [work-item]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# System Lab
+
+`/system-lab` is an optional advanced learning surface built from current repository/runtime evidence. It complements `/coach`; it does not replace the engineering workflow or authorize implementation changes.
+
+For detailed usage, model semantics, and examples, read `docs/process/SYSTEM_DESIGN_LEARNING_WORKBENCH.md` in a greenfield consumer (or canonical `core/process/SYSTEM_DESIGN_LEARNING_WORKBENCH.md`).
+
+## 1. Core contract
+
+- Start from the current repository and the minimum safe evidence needed for the requested lens.
+- Treat the repository/runtime/configuration evidence as authoritative; generated diagrams are disposable projections, never a second source of truth.
+- Re-discover evidence whenever the lab is invoked. Do not make the human remember to refresh or rebuild a diagram.
+- Prefer the distributed `tools/lean-system-lab/system-workbench.py` when present. It always rebuilds its model from current evidence and may compare with its prior disposable snapshot.
+- Never inspect Production credentials, Production data, or secret values.
+- Do not change production code, configuration, infrastructure, schemas, data, or deployment state while in System Lab mode.
+- Do not claim runtime behavior from static topology alone. Label evidence precisely.
+- Discovered implementation defects return to the normal engineering workflow; do not silently fix them here.
+- Learning is optional and never blocks delivery.
+
+## 2. Evidence labels
+
+Use these labels consistently:
+
+```text
+CONFIRMED BY CODE       — directly observed in source/configuration/tests
+CONFIRMED BY RUNTIME    — directly observed in safe runtime/telemetry evidence
+DOCUMENTED INTENT       — stated in project documentation/ADR/requirements
+INFERRED                — reasonable interpretation from incomplete evidence
+UNKNOWN                 — evidence is insufficient
+LEARNER ASSUMPTION      — value supplied for a design/capacity exercise
+```
+
+A diagram edge is not automatically proof that a runtime call occurred. A dependency discovered from configuration/package references may still be only structural evidence.
+
+## 3. System-design competencies
+
+Assess independently rather than using one generic "system design level":
+
+```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 the common L1-L6 levels, but record evidence per competency.
+
+## 4. Architecture lenses
+
+Treat one system model as the basis for multiple views:
+
+```text
+STRUCTURE      components and dependencies
+RUNTIME        request/event path for a scenario
+API            contracts, boundaries, callers, downstreams
+DATA           stateful components and data movement
+SCALE          load assumptions and bottleneck questions
+FAILURE        failure domains and propagation hypotheses
+CONSISTENCY    places state may disagree or ordering/idempotency matters
+PERFORMANCE    latency budgets, fan-out, saturation, timeout/retry behavior
+OBSERVABILITY  metrics/logs/traces/SLO evidence and gaps
+SECURITY       trust boundaries, authn/authz, secrets/PII exposure, abuse controls
+MESSAGING      producers/consumers, delivery semantics, ordering, retries, DLQ
+DEPLOYMENT     processes/containers/nodes/environments and rollout concerns
+TESTING        verification boundaries and untested risk
+CHANGES        architecture impact of the current/recent work item
+EVOLUTION      what complexity becomes justified as constraints change
+```
+
+If evidence for a lens is absent, show the gap instead of inventing detail.
+
+## 5. Interactive workbench
+
+When `tools/lean-system-lab/system-workbench.py` exists, prefer it for a current project snapshot.
+
+The tool is read-only and dependency-free. It:
+
+- scans current repository evidence for application/service/frontend/library/datastore/cache/messaging/external/deployment/test signals;
+- records provenance for inferred components and dependencies;
+- generates a stable evidence fingerprint and current Git commit when available;
+- automatically compares with the prior disposable snapshot in the selected output directory;
+- accepts optional explicit model JSON for richer known architecture, scenarios, failure behavior, decisions, SLOs, and metadata;
+- accepts changed-file paths so a delivered work item can be overlaid on the architecture;
+- creates self-contained `index.html` plus `workbench.json`;
+- supports draggable nodes, search, zoom, clickable nodes/edges, scenario highlighting, lens switching, change overlays, failure exploration, capacity calculations, latency budgets, scale/evolution prompts, design drills, and interview perturbations.
+
+Generate into a stable per-repository temp/cache directory so the prior disposable snapshot can be used for change comparison. Do not commit generated output unless explicitly requested.
+
+## 6. Scenario-to-architecture tracing
+
+For a scenario such as checkout, authentication, background processing, or notification:
+
+```text
+entry point
+→ participating components
+→ synchronous calls
+→ state reads/writes
+→ asynchronous messages
+→ external dependencies
+→ user-visible/result state
+```
+
+Highlight only evidence-backed participants. If the sequence is inferred from topology rather than captured runtime evidence, say so.
+
+Ask the learner to explain the path before filling gaps when that improves learning.
+
+## 7. Prediction before reveal
+
+For advanced learning, default to making the human predict before revealing the explanation when practical.
+
+Examples:
+
+```text
+What fails if this dependency times out?
+Which component becomes the bottleneck at 10x traffic?
+Where can duplicate delivery cause damage?
+Which signal would distinguish database latency from downstream latency?
+What consistency guarantee does the requirement actually need?
+```
+
+Do not turn every interaction into a quiz. Explanation-first remains valid when explicitly requested.
+
+## 8. Failure and debugging mode
+
+Failure mode should distinguish verified behavior from topological hypotheses.
+
+```text
+symptom/failure injection
+→ learner predicts impact
+→ identify failure boundary
+→ likely propagation
+→ distinguishing telemetry/evidence
+→ resilience behavior
+→ user-visible effect
+→ prevention/design alternatives
+```
+
+Useful perturbations include database/cache/queue/dependency unavailability, slow dependency, duplicate/delayed/out-of-order messages, retry amplification, queue backlog, regional failure, network partition, bad deployment, and traffic spikes.
+
+For `/system-lab debug`, reveal evidence incrementally and ask what evidence the learner would inspect next. Do not implement the fix in learning mode.
+
+## 9. Capacity and performance mode
+
+Use explicit learner/design assumptions, not invented production numbers.
+
+Connect:
+
+```text
+DAU / active users
+requests per user
+peak multiplier
+read/write mix
+payload size
+retention
+fan-out
+latency/SLO target
+```
+
+with derived average/peak RPS, write RPS, bandwidth, storage growth, and latency-budget reasoning. Explain simplifying assumptions.
+
+A scale slider or changed workload is a prompt to re-evaluate bottlenecks and complexity; it is not proof that a specific technology is required.
+
+## 10. Distributed-systems and messaging mode
+
+Practice:
+
+- strong/eventual/read-after-write consistency;
+- optimistic concurrency and conflict handling;
+- idempotency and deduplication;
+- at-least-once delivery and the limits of "exactly once" claims;
+- ordering and partitioning;
+- retry/backoff/DLQ behavior;
+- outbox/inbox patterns;
+- sagas/compensation;
+- distributed locks only when justified.
+
+Use timelines when helpful. Make the learner reason about state before and after duplicate, delayed, failed, or reordered events.
+
+## 11. API, security, observability, testing, and deployment lenses
+
+API:
+- contract shape, validation, versioning, auth, errors, pagination, idempotency, downstream coupling.
+
+Security:
+- trust boundaries, public exposure, authentication, authorization, secret handling, PII/data classification, replay/abuse/rate limiting.
+
+Observability:
+- logs, metrics, traces, SLOs, correlation, dependency health, saturation/queue depth, evidence gaps.
+
+Testing:
+- unit/integration/contract/e2e boundaries, failure-path coverage, architecture risks not currently exercised.
+
+Deployment:
+- artifact/process/container topology, environment/config boundaries, health/readiness, scaling, rollout/rollback, region/failure-domain assumptions.
+
+Treat missing evidence as a learning question, not a defect by itself.
+
+## 12. Architecture evolution and counterfactuals
+
+Use the current system as the baseline and explore changes such as:
+
+```text
+remove the cache
+make a synchronous path asynchronous
+increase traffic 10x/100x
+move from SQLite to a server database
+introduce multi-region requirements
+split or recombine a service
+add a queue/search/object store/CDN
+tighten latency/availability/privacy requirements
+```
+
+For each evolution:
+
+```text
+problem/evidence
+→ change
+→ expected benefit
+→ new complexity/failure modes
+→ migration path
+→ when NOT to do it
+```
+
+Prefer evolutionary design over cargo-cult complexity.
+
+## 13. Tradeoff and "why not?" drills
+
+Challenge choices with credible alternatives:
+
+```text
+Why not a monolith?
+Why not microservices?
+Why not Kafka/a queue?
+Why not synchronous HTTP?
+Why not cache this?
+Why not shard now?
+Why not retry here?
+Why not use the existing relational database?
+```
+
+The goal is to defend the simplest design that satisfies current constraints, then adapt when constraints materially change.
+
+## 14. Architecture decisions
+
+When ADRs or documented decisions exist, connect diagram components/edges to them. For each major choice discuss:
+
+```text
+context
+chosen decision
+alternatives
+tradeoffs
+consequences
+revisit trigger
+```
+
+Do not silently create durable ADRs in learning mode.
+
+## 15. Change-focused learning
+
+`/system-lab changes <work-item>` should focus on the accepted/delivered change set when evidence is available.
+
+Show:
+
+- added/removed/changed components and dependencies;
+- affected runtime/data/message paths;
+- newly introduced or materially changed failure modes;
+- new security/observability/performance/testing questions;
+- architecture decisions or assumptions worth explaining.
+
+A changed file is evidence that a component was touched, not proof that its runtime behavior changed. Keep that distinction visible.
+
+## 16. Interview mode
+
+Make the human drive:
+
+```text
+requirements
+→ constraints + scale assumptions
+→ API/contracts
+→ data/storage
+→ high-level architecture
+→ deep dive
+→ bottleneck/failure analysis
+→ consistency/reliability
+→ security/observability
+→ evolution
+→ tradeoff defense
+```
+
+Perturb one material constraint at a time: 20x traffic, multi-region, strict data residency, unreliable dependency, tighter p99, zero-downtime migration, duplicate delivery, cost pressure, or new abuse threat.
+
+Score/coach the independent system-design competencies rather than assigning one generic score.
+
+## 17. Cross-lab navigation
+
+System Lab owns system context; Database Lab owns schema/query/ORM/plan depth.
+
+When a system node represents a database, explicitly offer `/db-lab` for deeper relational/query evidence. When `/db-lab` reaches system-level concerns such as service boundaries, traffic, availability, or end-to-end runtime flow, offer `/system-lab`.
+
+Do not duplicate database internals inside System Lab or architecture reasoning inside Database Lab.
+
+## 18. Delivery-completion visibility
+
+After successful delivery, Lean may recommend the labs as optional learning while the change is fresh.
+
+- If database-related evidence changed, make `/db-lab` or `/db-lab changes <work-item>` visibly recommended.
+- If architecture/runtime/API/messaging/deployment/security/observability behavior changed, make `/system-lab` or `/system-lab changes <work-item>` visibly recommended.
+- If neither is especially relevant, the labs may remain visible as available options without claiming the ticket changed them.
+- Never use user-facing wording such as "rebuild the diagram" or "refresh the database model". Running a lab already means inspect current evidence and generate the current view.
+- Best-effort disposable artifact generation after delivery is allowed when safe and cheap, but failure to generate a learning artifact never changes delivery state.