@mriekki/project-forge 0.0.0-stage → 2.0.0

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

@@ -0,0 +1,90 @@
+# SQL / Database Learning and Drills
+
+Use the actual repository and domain whenever possible. SQL syntax is only one database competency; do not let query fluency hide weak relational design, indexing, transaction, or ORM reasoning.
+
+For evidence-backed hands-on exploration use `/db-lab`. For adaptive explanation, questioning, and reinforcement use `/coach`.
+
+## Competencies
+
+Assess independently using the common L1-L6 learning levels:
+
+- relational modeling and cardinality;
+- primary/foreign/candidate keys and integrity constraints;
+- normalization, anomalies, and deliberate denormalization;
+- query construction: joins, aggregates, GROUP BY/HAVING, subqueries/CTEs, pagination, deterministic sorting;
+- indexes and access-pattern reasoning;
+- query-plan interpretation and performance diagnosis;
+- transactions, isolation, concurrency, and failure behavior;
+- ORM translation, N+1 behavior, tracking/materialization, and abstraction leaks;
+- schema evolution and migration safety;
+- database debugging;
+- design defense and interview communication.
+
+## Query drill
+
+```text
+problem
+→ developer writes/predicts SQL
+→ correctness
+→ edge cases
+→ access pattern
+→ indexing/query-plan follow-up
+→ ORM translation when useful
+→ interview-style defense when useful
+```
+
+Do not reveal the complete query immediately unless the developer asks for explanation-first teaching.
+
+## Design drill
+
+```text
+requirements
+→ entities
+→ relationships/cardinality
+→ keys
+→ constraints
+→ normalization
+→ expected queries
+→ indexes
+→ transactions/concurrency
+→ migration/evolution concerns
+→ defend tradeoffs
+```
+
+Prefer practical anomaly questions over memorized normalization definitions.
+
+## Debugging drill
+
+```text
+symptom
+→ hypotheses
+→ SQL + parameters
+→ plan / constraints / transaction evidence
+→ root cause
+→ fix concept
+→ prevention
+```
+
+Use provider-native plan evidence where available and distinguish candidate indexes from indexes actually selected by the planner.
+
+## ORM drill
+
+Trace both directions:
+
+```text
+ORM/LINQ expression → generated/captured SQL → plan → result materialization
+SQL/schema constraint → ORM behavior/error → application-visible effect
+```
+
+When a framework exposes both a translation preview and actual executed commands, keep them distinct.
+
+## Suggested interview prompts
+
+- Model a many-to-many relationship that later needs attributes on the relationship itself.
+- Explain where uniqueness, nullability, and referential-integrity rules should be enforced.
+- Given three common queries, design only the indexes you can justify.
+- Diagnose why a query performs a scan instead of the expected indexed search.
+- Explain an N+1 problem and two credible fixes with tradeoffs.
+- Design a safe migration from nullable to required data.
+- Define a transaction boundary for a multi-table operation and discuss concurrency failure modes.
+- Defend when a surrogate key is preferable to a natural/composite key and when it is not.

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

@@ -0,0 +1,301 @@
+# System-Design Drills
+
+Start from the actual repository whenever possible. Use `/system-lab` when concrete architecture/runtime evidence is needed and `/coach system design` for conceptual/adaptive practice.
+
+Ask one material question at a time. Make the developer state assumptions and drive the design. For advanced exercises, prefer prediction before reveal.
+
+## Requirements and scope
+
+- Identify functional versus non-functional requirements.
+- Separate must-have V1 constraints from future scale assumptions.
+- Ask which guarantees actually matter: latency, availability, durability, consistency, privacy, cost, recovery.
+- Challenge unstated assumptions.
+- Ask what is explicitly out of scope.
+
+## Capacity and workload
+
+Give or elicit:
+
+```text
+users / active users
+requests per user
+peak multiplier
+read/write mix
+payload size
+retention
+fan-out
+latency target
+availability target
+```
+
+Have the learner estimate average/peak RPS, bandwidth, storage growth, and likely constrained resources before revealing calculated approximations.
+
+Perturb the workload:
+- 10x traffic;
+- 100x traffic;
+- read-heavy becomes write-heavy;
+- one tenant dominates load;
+- burst traffic replaces smooth traffic.
+
+Ask which architectural change becomes justified first and what evidence would prove it.
+
+## Architecture and decomposition
+
+- Explain current architecture from repository evidence.
+- Identify module/service boundaries and why they exist.
+- Propose a simpler architecture and defend why it is or is not sufficient.
+- Compare monolith/modular monolith/services for the current constraints.
+- Ask what would trigger extraction of a service rather than assuming microservices.
+- Identify stateful versus stateless components.
+- Identify synchronous versus asynchronous dependencies.
+
+## API and integration
+
+- Trace one endpoint from caller to state/dependencies.
+- Design request/response/error contracts.
+- Discuss versioning and compatibility.
+- Decide where validation/auth/idempotency belongs.
+- Reason about pagination, partial failure, timeouts, cancellation and retries.
+- Ask what happens when an external dependency is slow or unavailable.
+
+## Data and storage
+
+- Choose between relational, document, key-value, search and object storage based on access/integrity requirements.
+- Explain why the existing datastore is or is not enough.
+- Identify ownership of state across components.
+- Explore read replicas, partitioning/sharding and their complexity triggers.
+- Route schema/query/index deep dives to `/db-lab`.
+
+## Caching
+
+- What resource is the cache actually protecting?
+- What is the cache key and eviction/invalidation strategy?
+- What happens on stale data?
+- What happens when the cache disappears?
+- Could caching increase inconsistency or database stampede risk?
+- Why not avoid the cache until measurement justifies it?
+
+## Messaging and asynchronous workflows
+
+Use a timeline:
+
+```text
+state change
+→ publish
+→ consume
+→ side effect
+→ acknowledge
+```
+
+Perturb with:
+- duplicate message;
+- delayed message;
+- reordered message;
+- poison message;
+- consumer crash before/after side effect;
+- broker unavailable;
+- growing consumer lag.
+
+Ask where idempotency/deduplication belongs, what is durable at each step, and how retries/DLQ/compensation work.
+
+## Consistency and distributed coordination
+
+Practice:
+- strong versus eventual consistency;
+- read-after-write requirements;
+- optimistic concurrency;
+- lost update/conflict handling;
+- saga/compensation;
+- transactional outbox/inbox;
+- distributed locks only when justified;
+- why "exactly once" claims need careful qualification.
+
+Ask the learner to identify which business invariant requires which guarantee rather than choosing a consistency model by habit.
+
+## Failure and resilience
+
+Inject one failure at a time:
+
+```text
+database unavailable
+cache unavailable
+message delayed/duplicated
+third party times out
+one service becomes 5x slower
+queue backs up
+region unavailable
+network partition
+bad deployment
+traffic spike
+```
+
+Sequence:
+
+```text
+learner predicts impact
+→ identify propagation path
+→ identify distinguishing evidence
+→ discuss timeouts/retries/bulkheads/circuit breakers/fallbacks
+→ user-visible effect
+→ prevention/alternative
+```
+
+Challenge retry storms and hidden coupling.
+
+## Performance and latency
+
+Give a latency target and component estimates. Have the learner construct the budget.
+
+Perturb:
+- one dependency doubles latency;
+- fan-out increases;
+- p50 is fine but p99 regresses;
+- DB queries are fast but request latency is high;
+- synchronous work can become background work.
+
+Discuss tail latency, timeout budgets, parallelism, batching, queuing, caching and saturation.
+
+## Observability
+
+Ask:
+- Which metric detects the user-visible problem?
+- Which signal distinguishes application, datastore and dependency latency?
+- Where should trace spans exist?
+- What identifiers correlate logs/events/requests?
+- Which queue/saturation metrics matter?
+- What SLO/error budget expresses the requirement?
+- What cannot currently be diagnosed from available telemetry?
+
+## Security
+
+Map trust boundaries and ask:
+- Where are authentication and authorization enforced?
+- Where does PII/sensitive data flow?
+- How are secrets supplied without exposing values?
+- Can requests/messages be replayed?
+- What abuse/rate-limit controls are justified?
+- Which components should not be publicly reachable?
+- What changes under multi-tenant or data-residency requirements?
+
+Missing evidence is a question first, not automatic proof of a vulnerability.
+
+## Deployment and operations
+
+- Explain commit → CI → artifact → environment → running process/container.
+- Identify health/readiness checks.
+- Explain rollout and rollback strategy.
+- Identify failure domains and scaling units.
+- Explore regional deployment and recovery requirements.
+- Ask what configuration is deployment-specific and how secrets differ from configuration.
+- Separate merge from deployment authorization.
+
+## Testing and verification
+
+- Map tests to components/contracts.
+- Decide where unit/integration/contract/e2e tests provide useful confidence.
+- Identify failure paths that require more than unit tests.
+- Design a test for duplicate messaging, dependency timeout, rollout compatibility, or migration compatibility.
+- Ask which architecture risks are currently untested.
+
+Do not infer behavioral coverage from filenames alone.
+
+## Incident/debug drills
+
+Begin with a symptom, then reveal evidence gradually.
+
+Examples:
+- checkout p95 rises from 250 ms to 3 s;
+- error rate is stable but queue lag climbs;
+- database CPU is normal while request timeouts rise;
+- one region reports stale reads;
+- duplicate notifications appear after retries.
+
+Make the learner choose the next evidence source and explain what each observation rules in/out.
+
+## Architecture evolution
+
+Start from the current/simple system. Add complexity only in response to changed requirements/evidence.
+
+Explore:
+
+```text
+monolith → horizontally scaled app
+DB-only reads → justified cache
+synchronous task → background job/queue
+single DB → replicas/partitioning
+single region → multi-region
+shared module → extracted subsystem/service
+```
+
+For every step ask:
+
+```text
+What problem forces this change?
+What evidence supports it?
+What does it improve?
+What complexity/failure modes does it add?
+How would we migrate safely?
+When should we NOT do it?
+```
+
+## Counterfactual and "why not?" drills
+
+- What if Redis disappeared?
+- What if this request became asynchronous?
+- What if the queue were removed?
+- What if everything stayed in the relational database?
+- Why not keep a modular monolith?
+- Why not Kafka?
+- Why not retry here?
+- Why not shard now?
+- Why not cache everything?
+- Why not make this strongly consistent?
+
+The goal is to defend appropriate simplicity, not maximize the number of technologies.
+
+## Work-item change drills
+
+After a delivered ticket, use `/system-lab changes <work-item>` when relevant.
+
+Ask:
+- Which components were touched?
+- Which runtime/data/event paths may be affected?
+- What new or changed failure modes deserve attention?
+- Did security, observability, performance or test obligations change?
+- Which claim is confirmed versus inferred?
+- What architecture decision could now be defended in an interview?
+
+Use `/db-lab changes <work-item>` for database-specific consequences.
+
+## Interview mode
+
+Use a familiar project domain but change requirements enough that the learner cannot simply copy the repository.
+
+Drive:
+
+```text
+requirements
+→ scale assumptions
+→ API/contracts
+→ data/storage
+→ high-level architecture
+→ deep dive
+→ bottleneck/failure
+→ consistency/reliability
+→ security/observability
+→ evolution
+→ tradeoff defense
+```
+
+Then perturb one constraint:
+- traffic becomes 20x;
+- multi-region required;
+- data residency imposed;
+- third party unreliable;
+- p99 under 200 ms;
+- zero-downtime schema evolution required;
+- messages may duplicate;
+- cost must materially fall;
+- abuse threat increases.
+
+Assess independent competencies, explanation quality, credibility and adaptability rather than one generic system-design score.

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

@@ -0,0 +1,92 @@
+# Optional Coaching Guide
+
+Coaching is first-class but never required for engineering completion.
+
+## Depth
+
+```text
+1. Light — quick explanation/check
+2. Focused — one topic, moderate depth
+3. Deep — trace/apply/debug/defend
+4. Broad — survey related areas and identify gaps
+5. Let Coach recommend
+```
+
+## Modes
+
+```text
+1. Learn a concept
+2. Walk through real project code
+3. Debugging exercise/review
+4. Coding / DSA drill
+5. SQL / database drill
+6. Design defense
+7. System-design exercise
+8. Interview drill
+9. Learning-gap assessment
+10. Recommended learning path
+11. Docs / tutorial / video resources
+12. Return to engineering workflow
+```
+
+For a structured walkthrough of an implementation change set, use `/code-walkthrough`. It is the guided changed-file path under the coaching umbrella: resolve the actual Git/PR/commit diff, order files for understanding, explain functional and technical changes, and allow deeper tracing, diagrams, quizzes, debugging discussion, or interview practice without editing code.
+
+Use `/coach` for broader or ad-hoc concept learning. Use `/learning-review` when the primary goal is to assess whether the developer can explain and defend what was built.
+
+For hands-on database learning, `/db-lab` is the evidence-backed companion to Coach. Coach can teach database concepts, probe gaps, and run interview drills; Database Lab inspects the current project schema/ORM/query/migration/query-plan evidence, supports change-focused learning, and can drive query-to-ERD highlighting when an interactive workbench is installed. See `DATABASE_LEARNING_WORKBENCH.md`.
+
+For hands-on system-design learning, `/system-lab` is the evidence-backed companion to Coach. Coach can teach architecture/distributed-systems concepts, challenge assumptions, and run interview drills; System Lab inspects the current project architecture/runtime/API/dependency/messaging/deployment evidence and supports interactive scenario, failure, capacity, latency, security, observability, testing, evolution, and change-focused learning. See `SYSTEM_DESIGN_LEARNING_WORKBENCH.md`.
+
+Use the labs as siblings:
+
+```text
+system context / request-event flow / failure / scale
+                    ↕
+              /system-lab
+                    ↕
+          database component/node
+                    ↕
+                 /db-lab
+                    ↕
+schema / ORM / SQL / plans / migrations / constraints
+```
+
+Generated lab views are disposable projections of current evidence. Invoking a lab means re-discover the current evidence; the learner should not manually maintain or refresh diagrams.
+
+## Levels
+
+```text
+L1 Recognize
+L2 Explain
+L3 Trace
+L4 Apply / Debug
+L5 Defend / Design
+L6 Interview Ready
+```
+
+A useful optional sequence after stable implementation is:
+
+```text
+code walkthrough
+→ learning review
+→ targeted coaching / database lab / system lab as needed
+```
+
+After delivery, relevant labs may be surfaced again while the work-item change is fresh. The reminder is visible but never mandatory.
+
+For advanced DB/System learning, prefer prediction before reveal when practical:
+
+```text
+learner predicts
+→ reveal evidence
+→ reconcile gap
+→ apply/debug
+→ defend tradeoff
+→ change constraint
+```
+
+Explanation-first remains valid when requested.
+
+None of those learning activities is an engineering delivery gate.
+
+Once a coaching mode starts, continue automatically until stop or natural completion. Use the actual repository as the curriculum whenever possible. Learning trackers/resources remain optional.