@mriekki/project-forge 0.0.0-stage → 2.0.0

package/assets/generated/core/core/skills/core-sync/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: core-sync
+description: Direct Core-to-consumer synchronization for component-only consumers; package-managed consumers are routed to /project-forge-update so umbrella and component baselines remain coherent.
+argument-hint: "[optional local Core path]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Core Sync
+
+`/core-sync` is the direct component synchronization path for consumers that are managed directly by `CORE_BASELINE.json` **without** an umbrella `PROJECT_FORGE_BASELINE.json`.
+
+For package-managed consumers, `/project-forge-update` is authoritative.
+
+Invocation starts read-only. Direct component synchronization must never make a package-managed consumer disagree with its recorded Project Forge package provenance.
+
+## 1. Classify the consumer before doing anything else
+
+From the consumer repository read, when present:
+
+- `PROJECT_FORGE_BASELINE.json`;
+- `CORE_BASELINE.json`;
+- `.github/project-forge-workspace.json`;
+- `.github/project-forge-core-sync.json`;
+- current Git status, branch, remotes, and default branch when observable.
+
+### Package-managed consumer
+
+If `PROJECT_FORGE_BASELINE.json` exists:
+
+```text
+PACKAGE-MANAGED PROJECT FORGE CONSUMER
+Direct Core sync: NOT PERMITTED
+Next: /project-forge-update
+```
+
+Stop before refreshing a Core checkout, running `tools/package/sync.py`, creating a sync branch, or sending a remote `[sync-core]` request.
+
+The umbrella package updates Core and Deployment components together and refreshes `PROJECT_FORGE_BASELINE.json`, `CORE_BASELINE.json`, and `DEPLOYMENT_BASELINE.json` coherently. A Core-only sync would bypass that contract.
+
+### Component-only Core consumer
+
+If `PROJECT_FORGE_BASELINE.json` is absent and a valid `CORE_BASELINE.json` exists, continue with the component-managed path below.
+
+If neither baseline exists, report `CORE SYNC BLOCKED`; do not invent provenance or initialize a consumer implicitly.
+
+## 2. Establish the component-only Core baseline
+
+Run the repository-local integrity check before planning an update:
+
+```text
+python tools/project-forge-core/check-core-baseline.py --root .
+```
+
+Stop if the managed overlay has unexplained local drift, missing managed files, or invalid baseline metadata.
+
+Resolve from `CORE_BASELINE.json`:
+
+- canonical Core repository;
+- currently accepted Core commit/version;
+- distribution name;
+- managed-path ownership/hashes.
+
+## 3. Resolve the Core source safely
+
+Check local candidates in this order:
+
+1. an explicit Core path supplied by the human;
+2. an already-open workspace folder that unambiguously resolves to the recorded Core repository;
+3. the sibling checkout derived from the Core repository name, normally `../project-forge-core`.
+
+Do not broadly scan the filesystem. A local Core checkout is an optimization, not a prerequisite.
+
+A local candidate is usable only when it is the recorded Git repository and its state can be inspected safely.
+
+If no usable local Core checkout exists, use the configured remote provider from `.github/project-forge-core-sync.json` when available. Do not ask the developer to clone Core merely to satisfy `/core-sync`.
+
+## 4. Classify a local Core checkout
+
+Before modifying a local Core checkout inspect:
+
+```text
+git -C <core-path> status --short --branch
+git -C <core-path> branch --show-current
+git -C <core-path> remote -v
+git -C <core-path> branch -vv
+```
+
+It may be refreshed automatically only when clean, on its normal accepted/default branch, backed by an unambiguous upstream, and fast-forward-safe.
+
+Never auto-stash, merge, rebase, reset, clean, force-update, or discard Core work.
+
+If the checkout is dirty, ahead, diverged, intentionally pinned, or ambiguous, preserve it unchanged and prefer the configured remote provider when available.
+
+## 5. Present one bounded component-sync choice
+
+For a safe local source:
+
+```text
+CORE SYNC READY
+
+Consumer baseline: <commit/version>
+Source: LOCAL <core-path>
+Distribution: <distribution>
+
+1. Sync the component-only Core baseline [GIT + FILE WRITE] — recommended
+2. Keep inspecting only [READ ONLY]
+3. Stop [NO ACTION]
+```
+
+For a configured remote source:
+
+```text
+CORE SYNC READY
+
+Consumer baseline: <commit/version>
+Source: REMOTE PROVIDER
+Provider: <provider repository>
+
+1. Request remote Core sync [REMOTE WRITE] — recommended
+2. Keep inspecting only [READ ONLY]
+3. Stop [NO ACTION]
+```
+
+The selected choice does not authorize merge, release publication, or deployment.
+
+## 6. Local component path
+
+After local option 1 is selected:
+
+1. Refresh Core remote state.
+2. Reclassify the accepted/default Core branch.
+3. Fast-forward it only when safe.
+4. Run canonical Core sync preview using the distribution recorded by the baseline.
+5. Stop on `LOCAL_DRIFT`, `CONFLICT`, `LOCAL_MISSING`, `UNTRACKED_CONFLICT`, or an unaccepted `RETIRED_PATH`.
+6. If the consumer is on its default branch, create/switch to a short-lived branch such as `chore/sync-core-<version-or-short-sha>`.
+7. Apply only safe Core additions/updates and refresh `CORE_BASELINE.json` using canonical `tools/package/sync.py`.
+
+Do not manually copy managed files as a substitute for the canonical tool.
+
+## 7. Remote component path
+
+Remote orchestration is consumer configuration. Read `.github/project-forge-core-sync.json` and require its configured provider contract, for example `github-issue-control-plane` with an owner/repository title template and an empty body.
+
+Create exactly the configured request. Do not put product requirements, baseline JSON, source code, secrets, or other private consumer details into a public request.
+
+The provider is expected to validate target authorization, obtain its own short-lived credentials, run canonical Core sync, refuse unsafe drift/conflicts, publish a short-lived consumer branch/PR, and observe consumer CI.
+
+If the provider cannot satisfy that contract, report `REMOTE SYNC UNAVAILABLE`; do not silently clone Core or invent another synchronization mechanism.
+
+## 8. Verification
+
+For a local apply run:
+
+```text
+python tools/project-forge-core/check-core-baseline.py --root .
+git status --short --branch
+git diff --stat
+git diff -- CORE_BASELINE.json
+```
+
+Confirm exact Core provenance, managed hashes, consumer-owned preservation, and intended branch scope. Present the meaningful diff and recommend `/deliver` after human acceptance.
+
+For a remote path, report the resulting PR and exact Core commit when observed. Merge remains the normal explicit final gate.
+
+## 9. Boundaries
+
+`/core-sync` never:
+
+- directly synchronizes Core when `PROJECT_FORGE_BASELINE.json` exists;
+- uses direct Core sync as a substitute for `/project-forge-update`;
+- modifies ambiguous local Core state;
+- treats managed consumer drift as disposable;
+- publishes Core or Project Forge package releases/tags;
+- merges the consumer sync PR;
+- deploys production.
+
+If reusable Core behavior itself is wrong, fix Core canonically through `/upstream-fix`; then adopt it through the update channel appropriate to the consumer's provenance model.

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

@@ -0,0 +1,245 @@
+---
+name: db-lab
+description: "Optional project-aware database learning lab using actual schema, ORM, migration, query, and query-plan evidence for SQL, relational design, debugging, change exploration, and interview practice."
+argument-hint: "[schema|changes|trace|plan|debug|migration|interview|topic] [work-item] [light|focused|deep]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Database Lab
+
+`/db-lab` is an optional hands-on database learning surface. It complements `/coach`; it does not replace the engineering workflow or authorize implementation changes.
+
+For detailed usage and examples, read `docs/process/DATABASE_LEARNING_WORKBENCH.md` in a greenfield consumer (or the canonical `core/process/DATABASE_LEARNING_WORKBENCH.md`).
+
+## 1. Boundaries
+
+- Start from the **current** repository and its documented development/test database configuration.
+- Re-discover relevant database evidence whenever the lab is invoked. Running `/db-lab` means inspect current evidence and show the current view; do not make the human remember to refresh/rebuild an ERD.
+- Prefer read-only inspection. Do not mutate application data, apply migrations, add/drop indexes, or change production code while in Database Lab mode.
+- Never inspect Production credentials or Production data.
+- Do not invent schema, SQL, query-plan behavior, ORM translation, or index usage. Distinguish inferred behavior from captured evidence.
+- If safe local database/runtime evidence is unavailable, fall back to repository artifacts and say what could not be verified.
+- Generated learning artifacts are disposable projections of current evidence. Generate in temp/cache output and do not commit them unless explicitly requested.
+- Discovered implementation defects return to the normal engineering workflow; do not silently fix them here.
+- Learning is optional and never blocks delivery.
+
+## 2. Database competencies
+
+Use the common L1-L6 learning levels across independent database areas:
+
+```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
+```
+
+Do not collapse these into one generic "SQL level". A developer may be strong in query syntax and weak in relational design, indexing, transactions, or ORM translation.
+
+## 3. Schema mode
+
+Build an evidence-backed current view from the best available sources:
+
+```text
+physical database metadata
+ORM model/configuration
+migration history
+schema SQL / DDL
+project architecture and requirements
+```
+
+Show tables/entities, columns, types, nullability, primary keys, foreign keys, unique/check constraints, indexes, relationship cardinality, cascade behavior, and relevant ORM mappings when evidence exists.
+
+When useful, distinguish:
+
+```text
+DOMAIN MODEL   — what the application/domain expresses
+ORM MODEL      — what the ORM maps and tracks
+PHYSICAL MODEL — what the relational database actually stores/enforces
+```
+
+## 4. Change-focused mode
+
+`/db-lab changes <work-item>` should focus on the accepted/delivered change set when evidence is available.
+
+Show relevant changes to:
+
+- entities/tables and columns;
+- keys, constraints, relationships and cascade behavior;
+- indexes/access paths;
+- ORM mappings and generated SQL behavior;
+- migrations/schema evolution;
+- affected query paths;
+- transaction/concurrency assumptions.
+
+Connect each material change to the learning implication. A changed ORM/model file is evidence that persistence code was touched, not proof that the physical database changed; verify against migrations/schema/database evidence.
+
+When a previous disposable workbench snapshot exists, it may be used as a comparison aid. The current database/repository evidence remains authoritative.
+
+## 5. Query trace mode
+
+Trace a real application query without guessing:
+
+```text
+application/ORM expression
+→ ORM translation preview when available
+→ actual executed SQL when captured
+→ parameters
+→ tables/relationships touched
+→ query plan when available
+→ indexes actually chosen by the planner
+→ materialized/application result
+```
+
+Keep translation preview and actual executed command distinct when the framework exposes both.
+
+## 6. Query-to-ERD highlighting
+
+When the distributed SQLite workbench or another compatible viewer is available, a selected query should drive a linked ERD view:
+
+- highlight tables referenced by the SQL;
+- highlight FK edges when both related tables participate in the selected query;
+- highlight qualified query columns when they can be resolved to a table;
+- distinguish candidate indexes from indexes actually selected by the query planner;
+- show query-plan evidence alongside the diagram;
+- allow table/column/index selection for deeper explanation.
+
+Never claim the planner used an index merely because it exists or looks relevant.
+
+If no interactive viewer is available, provide a temporary Mermaid/text diagram using the same evidence and clearly label it as a fallback rather than a live ERD.
+
+## 7. SQLite workbench
+
+When `tools/project-forge-db-lab/sqlite-workbench.py` exists and a safe local development/test SQLite database is known, prefer it for physical-schema and query-plan evidence.
+
+The tool:
+
+- opens the SQLite database in `mode=ro`;
+- introspects tables/views, columns, primary keys, foreign keys, indexes, and DDL;
+- accepts optional captured-query JSON containing `name`, `sql`, and optional `parameters`;
+- uses `EXPLAIN QUERY PLAN` only for `SELECT`/`WITH` queries;
+- generates self-contained `index.html` plus `workbench.json` learning artifacts;
+- supports interactive table/index inspection and query-to-ERD highlighting.
+
+Generate output in a stable per-repository disposable/temp location when practical. Running the lab should regenerate the current view; an already-open older browser tab is not authoritative.
+
+The workbench analyzes captured SQL; it does not itself capture Entity Framework commands. Obtain translation/execution evidence through supported framework mechanisms first, then pass the captured SQL into the workbench when useful.
+
+## 8. Query-plan/performance mode
+
+Use provider-native plan evidence where safely available. Ask the developer to predict likely scans/searches/joins/index behavior before revealing the plan when that improves learning.
+
+```text
+query/access pattern
+→ developer prediction
+→ plan evidence
+→ explain scan/search/join behavior
+→ developer proposes index/query change
+→ predict changed plan
+→ compare evidence in a safe sandbox when available
+```
+
+Do not teach "add an index" without connecting it to a concrete access pattern, selectivity/order needs, write cost, and plan evidence.
+
+## 9. Debug mode
+
+```text
+symptom
+→ database hypotheses
+→ distinguishing evidence
+→ SQL / parameters
+→ plan / constraints / transaction state
+→ root cause
+→ fix concept
+→ prevention
+```
+
+The human should diagnose before the lab reveals the answer unless they explicitly request explanation-first coaching.
+
+## 10. Migration mode
+
+Connect:
+
+```text
+ORM migration/change
+↔ generated DDL/SQL when available
+↔ schema before
+↔ schema after
+↔ data-safety implications
+```
+
+Ask the developer to predict effects before showing generated SQL when useful. Discuss destructive changes, nullability transitions, backfills, constraint creation, and rollback limitations without applying migrations in learning mode.
+
+## 11. Interview/design mode
+
+Use the active project domain as context, but perturb requirements so the developer must reason rather than reproduce the existing schema.
+
+Drive one material question at a time through:
+
+```text
+requirements clarification
+→ entities
+→ relationships/cardinality
+→ keys
+→ constraints
+→ normalization
+→ access patterns
+→ indexes
+→ transactions/concurrency
+→ evolution/scaling
+→ design defense
+```
+
+Challenge unsupported choices. Ask why a junction table exists, why a key was selected, what deletion means historically, which queries justify an index, and how changed requirements alter the design.
+
+## 12. ORM-specific evidence
+
+When Entity Framework Core is present, distinguish:
+
+- LINQ/application expression;
+- translation preview such as `ToQueryString()` when appropriate;
+- actual executed `DbCommand` from supported logging/interception evidence;
+- generated migration SQL;
+- entity/change-tracking state versus physical SQL operations.
+
+Do not present a translation preview as proof of the exact command that executed.
+
+For other ORMs, apply the same principle using framework-supported evidence instead of guessing.
+
+## 13. Cross-lab navigation
+
+Database Lab owns database depth; System Lab owns end-to-end system context.
+
+When database exploration reaches service boundaries, request/event flow, traffic, availability, security, deployment, or system-wide failure behavior, offer `/system-lab` when installed.
+
+When `/system-lab` reaches a database node and the learner needs schema/query/index/ORM/plan depth, return to `/db-lab`.
+
+## 14. Delivery-completion visibility
+
+After successful delivery, Project Forge may visibly recommend `/db-lab` while the change is fresh when the accepted diff changed database-related evidence such as entities, migrations, schema, SQL/query code, repository/persistence behavior, indexes, constraints, or transaction logic.
+
+Prefer learner-facing wording such as:
+
+```text
+★ /db-lab changes WI-24
+  This work changed database structure or behavior.
+  Explore affected relationships, queries, indexes, constraints, and ORM behavior.
+```
+
+Do **not** say "rebuild the database diagram" or "refresh the model". Current evidence is part of invoking the lab.
+
+Best-effort disposable workbench generation after delivery is allowed only when a safe development/test database is already known. Do not guess a database path, create/apply migrations, or touch Production just to generate a learning artifact. Generation failure never changes delivery state.
+
+## 15. Tooling
+
+Optional IDE/database extensions may improve exploration but are not workflow authority and must not become a required dependency unless the project explicitly owns that requirement.
+
+Prefer provider/framework-native inspection plus repository evidence. The SQLite workbench is a reusable read-only learning aid; future provider/ORM adapters should preserve the same evidence, current-by-default behavior, and safety contract.

package/assets/generated/core/core/skills/define-feature/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: define-feature
+description: Define or clarify a feature, initiative, engineering enabler, or other work item while respecting the configured source-of-truth and optional brief model.
+argument-hint: "<work-item ID, external key, idea, or topic>"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Define Feature
+
+Keep discovery proportional. Do not turn a small change into a ceremony.
+
+## 1. Resolve authority first
+
+Read `.github/project-forge-workspace.json` when present before assuming a document hierarchy.
+
+Possible authoritative sources include:
+- Jira Story/Epic,
+- GitHub Issue,
+- local Product/Feature/Enabler brief,
+- local requirements,
+- another team work-item system,
+- small session context for trivial work.
+
+Use external work-item content only when it is actually available. Never claim a Jira/Issue was read when it was not.
+
+Never assume `Jira Epic == Feature Brief`.
+
+## 2. Classify the request
+
+Classify as one of:
+- Product Feature,
+- Engineering Enabler,
+- Small Change / Task,
+- Cross-Cutting Requirement / Standard,
+- ADR-worthy Architecture Decision,
+- Future Roadmap Idea.
+
+Do not invent user stories for technical foundation work.
+
+## 3. Respect brief modes
+
+Product/Feature Brief modes may be:
+
+```text
+not-used
+read-existing
+supplemental-experimental
+authoritative
+suggest-complex
+```
+
+Behavior:
+- `not-used`: do not create the brief.
+- `read-existing`: read when relevant; do not create/update.
+- `supplemental-experimental`: an optional brief may be proposed, clearly labeled non-authoritative.
+- `authoritative`: use/update the configured brief as authority.
+- `suggest-complex`: recommend a brief only when cross-work-item or workflow complexity makes it useful.
+
+Do not create a competing source of truth.
+
+## 4. Discovery cadence
+
+Ask one material question at a time when a real decision is unresolved.
+
+For bounded decisions with a small credible answer space, use the choice-first interaction guidance from `INTERACTIVE_SESSION_GUIDE.md`. Keep initial product/problem framing, desired outcomes, workflows, and other answers that need the human's own wording open-ended rather than constraining them to invented options.
+
+Clarify only what matters, such as:
+- user/engineering outcome,
+- scope and non-scope,
+- important workflows/lifecycle,
+- domain/engineering invariants,
+- destructive/reversible behavior,
+- security/privacy expectations,
+- dependencies,
+- acceptance summary,
+- open decisions.
+
+Record unresolved decisions explicitly rather than inventing them.
+
+## 5. Detailed requirements are proportional
+
+Create/refine detailed requirements only when precision is useful.
+
+When local detailed requirements are permitted and useful, prefer one combined file.
+
+Product Feature:
+
+```text
+requirements.md
+├── User Stories
+├── Domain Requirements
+├── Acceptance / Validation Scenarios
+├── Open Decisions
+├── Traceability
+└── Approval
+```
+
+Engineering Enabler:
+
+```text
+requirements.md
+├── Engineering Requirements
+├── Acceptance Criteria / Validation Scenarios
+├── Open Decisions
+├── Traceability
+└── Approval
+```
+
+If the configured external work item is primary and local detailed requirements are not an approved supplement, propose updates to that external source instead of creating local duplicate authority.
+
+## 6. Stop boundary
+
+Stop before implementation.
+
+Do not create an implementation plan or production code as part of `/define-feature`.
+
+If systematic lower-level coverage is valuable, recommend:
+
+```text
+/refine-requirements <ID-or-key>
+```
+
+## 7. Guided ending
+
+Use a small evidence-backed menu, for example:
+
+```text
+CURRENT STATE
+<what is defined and what remains open>
+
+RECOMMENDED NEXT STEP
+<one action and why>
+
+OPTIONS
+1. Review definition [READ ONLY]
+2. Grill unresolved behavior [READ ONLY]
+3. Refine detailed requirements [READ ONLY initially]
+4. Approve requirements/scope when applicable [REQUIREMENTS GATE]
+5. Start work if already ready [READ ONLY]
+6. Stop [NO ACTION]
+```
+
+Only show relevant options. A file-changing choice authorizes only that bounded action/session.