@mriekki/project-forge 0.0.0-stage → 2.0.0

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

@@ -0,0 +1,397 @@
+# Database Learning Workbench
+
+The Database Learning Workbench is the reusable Project Forge learning contract behind `/db-lab`. It makes database behavior that frameworks and ORMs often hide visible enough to inspect, explain, debug, and defend.
+
+It is project-aware rather than a generic SQL course: use the **current** repository's domain, schema, migrations, ORM mappings, queries, and safe development/test database evidence as the curriculum.
+
+Learning remains optional and never changes engineering delivery state.
+
+## Quick start
+
+Use `/coach` for explanation, adaptive questioning, and gap assessment. Use `/db-lab` when the learning needs concrete database evidence.
+
+```text
+/coach database design
+/db-lab
+/db-lab schema
+/db-lab changes <work-item>
+/db-lab trace <query/file/symbol>
+/db-lab plan <query>
+/db-lab debug <symptom/query>
+/db-lab migration <migration>
+/db-lab interview database
+```
+
+Invoking `/db-lab` means **inspect current evidence and show the current view**. The learner should not need to remember to refresh, rebuild, or manually maintain an ER diagram.
+
+Natural-language arguments are preferred over rigid syntax. Examples:
+
+```text
+/db-lab show me how Recipes and Ingredients are related
+/db-lab changes WI-24
+/db-lab trace the EF query used by GetWeeklyMealPlan
+/db-lab why is this query scanning MealPlanItems
+/db-lab show which indexes this query actually uses
+/db-lab walk me through the latest migration without applying it
+/db-lab give me a database-design interview based on this domain
+```
+
+## Current-by-default artifact lifecycle
+
+Generated workbench HTML/JSON is a disposable projection:
+
+```text
+current safe database/repository evidence
+→ inspect schema / ORM / migrations / queries
+→ build current learning model
+→ generate current interactive view
+```
+
+The database/repository evidence remains authoritative. An older browser tab is not authoritative. Run the lab again and it produces the current view.
+
+When a previous disposable snapshot is available it may help explain what changed, but never outranks current physical/ORM/migration evidence.
+
+## SQLite interactive workbench
+
+Greenfield consumers that include the Core learning payload receive:
+
+```text
+tools/project-forge-db-lab/sqlite-workbench.py
+```
+
+The tool is dependency-free Python and opens SQLite databases read-only. It generates a self-contained interactive `index.html` and machine-readable `workbench.json`.
+
+### PowerShell
+
+From the repository root, using a **known safe development/test** SQLite file:
+
+```powershell
+Set-Location D:\Projects\<repo>
+$out = Join-Path $env:TEMP "project-forge-db-lab"
+python .\tools\project-forge-db-lab\sqlite-workbench.py export `
+  --db .\.data\app.db `
+  --out $out
+Start-Process (Join-Path $out "index.html")
+```
+
+`.data/app.db` is only an example. Use the actual project development/test database path. Never point the learning tool at Production.
+
+### macOS/Linux
+
+```bash
+cd /path/to/repo
+out="${TMPDIR:-/tmp}/project-forge-db-lab"
+python3 tools/project-forge-db-lab/sqlite-workbench.py export \
+  --db .data/app.db \
+  --out "$out"
+open "$out/index.html" 2>/dev/null || xdg-open "$out/index.html"
+```
+
+### Query-to-ERD evidence
+
+Create a disposable query-evidence JSON file from captured or otherwise verified SQL:
+
+```json
+[
+  {
+    "name": "Get weekly meal plan",
+    "sql": "SELECT r.Id, r.Name FROM MealPlanItems mpi JOIN Recipes r ON r.Id = mpi.RecipeId WHERE mpi.MealPlanId = :mealPlanId",
+    "parameters": {
+      "mealPlanId": 42
+    }
+  }
+]
+```
+
+Run the workbench with that evidence:
+
+```powershell
+$out = Join-Path $env:TEMP "project-forge-db-lab"
+python .\tools\project-forge-db-lab\sqlite-workbench.py export `
+  --db .\.data\app.db `
+  --queries .\tmp\db-lab-queries.json `
+  --out $out
+Start-Process (Join-Path $out "index.html")
+```
+
+Each invocation produces the current view. The query-evidence file and generated workbench stay disposable/local unless the project explicitly chooses a sanitized durable artifact.
+
+## What the interactive viewer shows
+
+The SQLite workbench supports:
+
+- tables and views;
+- columns, types, nullability, and primary-key participation;
+- foreign-key relationships and delete/update actions;
+- indexes, uniqueness, origin, partial-index status, key columns, and stored DDL when available;
+- junction-table candidates, clearly labeled as a heuristic rather than domain truth;
+- clickable tables, columns, and indexes with a learning/details panel;
+- query selection and highlighting of referenced tables;
+- relationship-edge highlighting when both related tables participate;
+- qualified query-column highlighting when resolvable;
+- `EXPLAIN QUERY PLAN` evidence for parameterized `SELECT`/`WITH` queries;
+- a distinction between indexes selected by the planner and indexes that are merely plausible candidates/relevant to highlighted columns.
+
+The viewer does not claim to understand arbitrary SQL perfectly. SQL-to-table/column mapping includes heuristic parsing, while planner-selected indexes come from SQLite's own query-plan evidence.
+
+## What to expect from `/db-lab`
+
+A useful session follows evidence rather than guesses:
+
+```text
+repository intent
+→ ORM model
+→ physical schema
+→ query / executed SQL
+→ query plan
+→ indexes / constraints / transaction behavior
+→ explanation or exercise
+```
+
+Explicitly state which layers were verified and which were inferred.
+
+Where useful, distinguish:
+
+```text
+DOMAIN MODEL
+ORM MODEL
+PHYSICAL MODEL
+```
+
+## Change-focused learning
+
+Prompt:
+
+```text
+/db-lab changes WI-24
+```
+
+Use the accepted/delivered change set plus current database evidence. Explain relevant changes to:
+
+- entities/tables and columns;
+- primary/foreign/unique/check constraints;
+- nullability and cascade behavior;
+- indexes and access paths;
+- ORM mappings and translation behavior;
+- migrations/DDL and data-safety implications;
+- query paths;
+- transactions/concurrency.
+
+A changed entity/migration/query file proves that database-related code was touched. It does **not** by itself prove that the physical database changed. Verify the physical layer when safe evidence is available.
+
+A good learning summary connects the change to its consequence:
+
+```text
+added relationship
+→ new FK/invariant
+→ new join/access path
+→ possible index consideration
+→ migration/data compatibility question
+```
+
+## Entity Framework to raw SQL
+
+For EF Core, connect:
+
+```text
+LINQ / EF expression
+→ translation preview such as ToQueryString() when appropriate
+→ captured actual DbCommand when available
+→ parameters
+→ tables and relationships
+→ provider query plan
+→ indexes selected by the planner
+→ result materialization/tracking
+```
+
+Translation preview and an actually executed command are different evidence. Label them separately. Use supported logging/interception for executed-command evidence; the SQLite workbench consumes captured SQL and does not replace EF command capture.
+
+Apply the same principle to other ORMs using framework-supported mechanisms.
+
+## Query-to-ERD highlighting
+
+For a query touching `MealPlans`, `MealPlanItems`, and `Recipes`, highlight those tables. If both ends of an FK relationship participate, emphasize the edge. Highlight resolvable qualified columns.
+
+If `EXPLAIN QUERY PLAN` says an index was used, mark it **planner selected**. An index whose leading column appears relevant but was not selected can be shown as **candidate/relevant**, never as used.
+
+If the interactive viewer is unavailable, use a temporary Mermaid/text diagram and clearly label the fallback.
+
+## Query-plan debugging
+
+Preferred learning sequence:
+
+```text
+show query/access pattern
+→ developer predicts plan/index behavior
+→ inspect provider-native plan
+→ identify scan/search/join evidence
+→ developer proposes a change
+→ predict changed plan
+→ compare safely when a sandbox is available
+```
+
+Do not teach "add an index" without connecting it to a concrete access pattern, selectivity/order needs, write cost and plan evidence.
+
+## Migration review
+
+Prompt:
+
+```text
+/db-lab migration AddRecipeRatings
+```
+
+Connect:
+
+```text
+migration intent
+↔ migration/ORM operations
+↔ generated SQL/DDL when available
+↔ schema before
+↔ schema after
+↔ data-safety concerns
+```
+
+Useful questions:
+
+- Is existing data compatible with a new non-null column?
+- Is a backfill required?
+- Does a uniqueness constraint match the invariant?
+- Is a table rebuild/destructive operation involved?
+- What rollback limitations exist?
+
+Do not apply the migration in Database Lab mode.
+
+## Database-design interview
+
+Prompt:
+
+```text
+/db-lab interview database
+```
+
+Use the project domain for familiarity but perturb requirements so memorizing the schema does not solve the exercise.
+
+Drive:
+
+```text
+requirements
+→ entities
+→ relationships/cardinality
+→ keys/constraints
+→ normalization
+→ access patterns
+→ indexes/plans
+→ transactions/concurrency
+→ evolution/scaling
+→ design defense
+```
+
+Ask why a junction table exists, why a key was chosen, what deletion means historically, which query justifies an index, which invariant belongs in a database constraint, and what changes under concurrent edits.
+
+## Database competency model
+
+```text
+relational modeling
+keys + integrity constraints
+normalization + data anomalies
+SQL query construction
+indexes + access patterns
+query plans + performance reasoning
+transactions + concurrency
+ORM translation + abstraction leaks
+schema evolution + migrations
+database debugging
+design defense + interview communication
+```
+
+Use L1-L6 per competency rather than one undifferentiated SQL score.
+
+## Cross-lab learning
+
+System Lab owns system context; Database Lab owns database depth.
+
+```text
+/system-lab runtime checkout
+→ identify Orders DB
+→ /db-lab trace <order query>
+
+/db-lab plan <query>
+→ database evidence looks healthy but end-to-end latency is high
+→ /system-lab performance checkout
+```
+
+## Delivery-completion visibility
+
+Successful delivery may visibly recommend:
+
+```text
+★ /db-lab changes WI-24
+  This work changed database structure or behavior.
+  Explore affected relationships, queries, indexes, constraints, and ORM behavior.
+```
+
+When database-specific evidence was not materially touched, `/db-lab` may still appear as an available option:
+
+```text
+○ /db-lab
+  Explore the current database schema, relationships, queries, indexes, and ORM behavior.
+```
+
+Do not tell the learner to rebuild or refresh a diagram. Current evidence is part of invoking the lab.
+
+After successful merge/default-branch CI, `/deliver` may prepare a disposable SQLite workbench automatically only when the accepted change is DB-relevant, the tool exists, and a safe local development/test SQLite database path is already known. Never guess the path, create/apply migrations, mutate data, or touch Production just to prepare learning output. Failure remains non-blocking.
+
+## Provider / ORM architecture
+
+The workbench stays provider/ORM-adapter oriented rather than application-specific.
+
+```text
+Database adapter
+  SQLite concrete path
+  PostgreSQL / SQL Server / ... future
+
+ORM evidence
+  EF Core first concrete path
+  Hibernate / SQLAlchemy / ... future
+
+Canonical learning model
+  tables
+  columns
+  constraints
+  relationships
+  indexes
+  queries
+  query-plan steps
+  migrations
+
+Interactive viewer
+  schema navigation
+  learning panels
+  query-to-ERD highlighting
+```
+
+SQLite + EF Core is a first concrete learning path, not a permanent architectural restriction.
+
+## IDE tooling
+
+Database extensions can improve the human exploration loop, but `/db-lab` must not depend on manipulating their UI.
+
+For SQLite projects, Bootstrap may recommend SQLTools plus its SQLite driver so the developer can independently browse/query the same local database. The reusable lab obtains authoritative evidence from repository/framework/provider-supported mechanisms.
+
+## Safety and fallbacks
+
+Database Lab is read-only learning by default.
+
+Do not:
+
+- connect to Production for learning exercises;
+- mutate application data;
+- apply/revert migrations;
+- create/drop indexes;
+- change code to prove a point;
+- claim an index was used without plan evidence;
+- manufacture executed SQL when only ORM source is available.
+
+The SQLite workbench opens the database with SQLite `mode=ro`. Generated HTML/JSON are disposable learning artifacts and should normally go to temp/cache rather than tracked project paths.
+
+If evidence is missing, say so and continue with the strongest safe layer available. A missing database runtime, ORM trace, interactive viewer, or post-delivery artifact should degrade the experience; it should never block learning or engineering delivery.

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

@@ -0,0 +1,166 @@
+# Deployment Enablement
+
+Deployment enablement is the guided operational lane between delivered deployment engineering and `/deploy`.
+
+A **logical environment is not a physical computer**. A repository may define `demo`, `staging`, `production`, or other named environments; one developer may use only a workstation, several environments may share one VPS, or a desired deployment may remain explicitly deferred.
+
+The normal human-facing entry point is state-driven:
+
+```text
+/deployment-readiness <environment>
+```
+
+Read-only overview:
+
+```text
+/deployment-readiness status [environment]
+```
+
+The workflow discovers current topology/state and continues from the furthest safe point. The human does not choose separate `discovery`, `enable`, or `resume` modes.
+
+## Topology before machine questions
+
+Resolve these independently when repository evidence provides them:
+
+```text
+environment name / role / purpose
+placement
+isolation
+exposure
+binding state
+adapter
+target/provider binding
+failure domain
+```
+
+Current placement classes include:
+
+- `workstation` — local execution; current reusable container adapter is loopback-only;
+- `remote-target` — an explicitly bound remote machine/target;
+- `managed-service` — only when a provider-specific adapter actually exists;
+- `deferred` — desired deployment exists but no current target/provider binding is selected.
+
+Do not ask remote-machine questions until `remote-target` is actually the selected placement.
+
+## Workstation readiness
+
+A one-machine local/demo topology is normal.
+
+For current `workstation-container` support, readiness focuses on:
+
+- local Docker/runtime availability;
+- repository-distributed local deployment tooling;
+- exact immutable artifact/image identity;
+- local port/container ownership and health configuration;
+- persistence prerequisites where relevant;
+- Production policy if the logical environment is Production.
+
+It does not require SSH, a hostname, target profile, host trust, Caddy, Avahi, or a second computer.
+
+The adapter's current exposure is loopback. Do not silently widen it to LAN/public sharing.
+
+## Remote-target readiness
+
+For remote placement, retain the strict target/access model:
+
+```text
+named environment
+→ explicit target binding
+→ current address/discovery
+→ independently verified host identity
+```
+
+Human-facing facts normally include hostname/IP, deployment user, non-default port, and target OS when relevant.
+
+Internal target/profile/SSH/trust paths should be discovered, reused, or derived whenever possible rather than pushed onto the human as first questions.
+
+If existing configuration is present, show known facts for confirmation. If partial, ask only for the smallest missing fact. If absent, start with the actual machine/address rather than an internal target identifier.
+
+Remote probing requires explicit read-only authorization. Address discovery never substitutes for cryptographic host identity. Unknown/changed SSH identity fails closed.
+
+## Deferred readiness
+
+A deferred placement is intentional configuration state:
+
+```text
+DEPLOYMENT INTENTIONALLY DEFERRED
+```
+
+It must not block repository generation, local development, CI, documentation, or learning. Readiness should explain the next material decision—choose/configure a supported target/provider adapter—without guessing infrastructure or asking for secrets.
+
+## Managed-service boundary
+
+Managed hosting is adapter-specific. General model knowledge may recommend a provider, but absent a live catalog/implementation contract it remains `CATALOG GAP`/planned.
+
+No provider credentials or provisioning should occur merely because a deployment outcome is public/shareable.
+
+## Colocated environments
+
+Two logical environments may intentionally share one physical failure domain.
+
+Keep their targetable scope, runtime/container, route, data, readiness evidence, and authorization independent. When Staging and Production share one target, surface:
+
+```text
+TOPOLOGY NOTE
+
+Staging and Production are logically isolated but share one physical
+failure domain. This may fit POC cost/learning goals, but it does not
+demonstrate host-level Production isolation.
+```
+
+Production backup/recovery/security/deploy/destructive gates remain stronger regardless of colocation.
+
+## Readiness cadence
+
+```text
+select environment
+→ resolve topology
+→ inspect placement-relevant local state
+→ show/confirm known facts
+→ authorize relevant read-only verification
+→ repair only missing prerequisites under explicit write gates
+→ ENVIRONMENT READY TO DEPLOY
+→ /deploy <environment>
+```
+
+For workstation placement there is no remote-access stage. For deferred placement the workflow intentionally stops before verification/provisioning.
+
+## Readiness writes versus deployment writes
+
+Readiness may perform bounded setup writes when separately authorized and supported by installed tooling, such as local configuration, SSH key/agent/trust setup, target-side access setup, runtime/platform preparation, data/backup directories, firewall preparation, or registry/provider credential configuration.
+
+Readiness does **not** hide application deployment inside setup.
+
+Application runtime deployment, release-specific migration, route/port publication, live health/readiness, smoke validation, and release-specific evidence belong to `/deploy` when the installed adapter defines them.
+
+## Pre-deploy versus post-deploy evidence
+
+Readiness proves only facts that can exist before deployment, such as:
+
+- logical environment/topology selection;
+- supported adapter availability;
+- local Docker readiness or verified remote target/identity depending on placement;
+- target OS/runtime when applicable;
+- artifact identity/access;
+- route/port ownership availability;
+- persistence/backup/migration prerequisites;
+- deployment lock/recovery capability;
+- stronger Production prerequisites.
+
+First-deploy live route, health, smoke, deployed-release identity, and release-specific rollback evidence are post-deploy facts owned by `/deploy`.
+
+## Environment independence
+
+Readiness of one logical environment never proves another environment ready—even if both share one physical target.
+
+Failure of one environment never redirects to another environment, machine, provider, or wider exposure.
+
+Production remains a logical role/policy with stronger gates, not a separate readiness command or a requirement for a dedicated physical computer.
+
+Once ready:
+
+```text
+/deploy <environment>
+```
+
+`/deploy` verifies current topology/target/artifact evidence, presents the exact installed-tool authorization gate, delegates deterministic mechanics, and verifies placement-relevant live evidence.

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

@@ -0,0 +1,48 @@
+# Guided Next Steps
+
+Substantial Project Forge interactions should not end with a vague `Next:` sentence.
+
+Use evidence-backed guidance:
+
+```text
+CURRENT STATE
+<what is actually known>
+
+RECOMMENDED NEXT STEP
+<one action and why>
+
+OPTIONS
+1. ... [READ ONLY]
+2. ... [MODIFIES DOCS]
+3. ... [MODIFIES FILES]
+4. ... [GIT + GITHUB WRITE]
+5. Stop [NO ACTION]
+
+RECOMMENDED PATH
+<only when multiple future steps are useful>
+```
+
+Show only relevant options.
+
+Standard action labels include:
+
+```text
+[READ ONLY]
+[MODIFIES DOCS]
+[MODIFIES FILES]
+[REQUIREMENTS GATE]
+[HUMAN ACCEPTANCE]
+[GIT WRITE]
+[GITHUB WRITE]
+[GIT + GITHUB WRITE]
+[REMOTE READ ONLY]
+[REMOTE WRITE]
+[PRODUCTION WRITE]
+[NO ACTION]
+```
+
+A selected option authorizes only the bounded action described, except where a skill explicitly defines a continuous session or compound mechanical action.
+
+A manually invoked compound action skill may itself be the bounded authorization for its routine mechanics. `/deliver`, for example, may proceed through safe short-lived-branch setup/recovery, staging, commit, push, PR creation/update, and CI inspection without inserting separate options for each mechanical step. It still stops at its explicit merge/finalize gate and whenever evidence becomes ambiguous or unsafe.
+
+Conversation may continue automatically; consequential decisions remain explicitly gated.

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

@@ -0,0 +1,83 @@
+# Human Gates
+
+Use explicit human gates where consequences warrant them.
+
+Typical gates:
+- workspace/setup acceptance before the first substantive work item,
+- material requirements/scope approval when detailed requirements matter,
+- substantive implementation-plan approval for STANDARD/ELEVATED work,
+- meaningful local implementation/diff acceptance,
+- merge/final-delivery decision after PR CI when the PR still matches the accepted implementation,
+- unrelated/out-of-band branch deletion when not already covered by a bounded delivery/cleanup choice,
+- external/remote/system writes not already covered by an explicitly invoked bounded workflow,
+- first production deployment,
+- destructive recovery/restore,
+- publishing a release/tag.
+
+Workspace/setup acceptance is distinct from generation or installation. Generated files, installed tools, operational dependencies, editor/agent discovery, and human usability are separate facts. A setup script or static diagnostic may provide evidence, but only the human accepts the checkout as ready for the next intended work item.
+
+A human gate is meaningful only when the human understands what is being approved. If the explanation immediately before a gate did not land, re-explain it before asking for approval again. `/wait-what` is the standard read-only communication-repair path when available; invoking it never implies approval of the pending action.
+
+Do not gate routine mechanics individually after a bounded action is already authorized.
+
+Missing access to GitHub admin policy metadata is not itself a human gate. Use configured workflow/check results, PR mergeability, repository documentation, and any observable enforced policy as evidence. Do not ask the human to open GitHub Settings and transcribe branch-protection/ruleset check names merely to continue; ask only when unavailable policy information creates a material unresolved decision at merge, release, or another consequential action.
+
+## Implementation branch setup
+
+Once implementation itself is authorized, creating/switching to the repository-appropriate short-lived work branch is routine setup, not a separate decision gate, when branch policy/naming and work-item scope are clear and the operation preserves the worktree without history rewriting.
+
+For STANDARD/ELEVATED work, this branch setup follows plan approval. For LIGHT work, it is part of the human-selected implementation action.
+
+Stop only when branch choice/state is ambiguous, unrelated work is present, or the operation would require stash/reset/rebase/force/history rewriting.
+
+## Streamlined /deliver authorization
+
+Because `/deliver` is manually invoked after implementation review and meaningful local acceptance, invoking it is one bounded authorization for routine delivery mechanics within that accepted scope:
+
+```text
+recover/create the short-lived branch when needed
+→ selective stage
+→ staged-diff verification
+→ commit-message generation
+→ commit
+→ normal push
+→ create/update PR
+→ PR-body population
+→ PR-CI inspection/rechecks
+```
+
+Do not separately ask `Create branch?`, `Commit?`, `Push?`, `Create PR?`, or `Check CI?` when those actions remain safe and within scope.
+
+`/deliver` invocation does **not** authorize merge, production deployment, force push, code fixes after CI failure, unrelated branch deletion, scope expansion, or destructive/history-rewriting Git operations.
+
+## Combined final acceptance + merge gate
+
+When the PR head/diff still exactly represents the implementation the human already accepted locally, Reviewer is READY, configured PR CI is green, any additional observable repository-required checks are satisfied, and repository policy/mergeability are satisfactory, final PR acceptance and merge authorization may be combined into one meaningful choice:
+
+```text
+Merge and finalize delivery [HUMAN ACCEPTANCE + GITHUB/GIT WRITE]
+```
+
+That explicit choice covers only the observed PR and its normal short-lived delivered branch. It authorizes:
+- final acceptance of the PR as observed,
+- merge using the approved repository strategy,
+- observation/recheck of applicable post-merge default-branch CI/policy,
+- safe finalization of that delivered short-lived branch after that CI/policy evidence is satisfied.
+
+It does not authorize deleting any other branch, bypassing changed evidence, or deploying to production.
+
+If new commits, material diff changes, conflicts, or regressed checks appear after local acceptance, final PR review becomes a real gate again before merge.
+
+If the repository/human explicitly requires branch retention, preserve the delivered branch. If safe cleanup cannot be proven, preserve it and report the exact reason rather than inserting another ceremonial prompt.
+
+A later production deployment, unrelated branch cleanup, release publication, destructive recovery action, or newly changed implementation remains a separate explicit gate.
+
+The principle is:
+
+```text
+conversation continues automatically
+routine mechanics are grouped when safe
+branch setup/finalization are automatic inside explicit bounded workflows
+changed evidence re-opens the relevant review gate
+consequential decisions remain human-controlled
+```