@mriekki/project-forge 0.0.0-stage → 2.0.0

package/assets/generated/core/core/skills/deployment-readiness/SKILL.md

@@ -0,0 +1,234 @@
+---
+name: deployment-readiness
+description: Guided readiness for any exact project-defined deployment environment. Resolves logical topology first, reuses valid setup-time proof, and verifies only placement-relevant prerequisites.
+argument-hint: "[environment] | status [environment]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Deployment Readiness
+
+`/deployment-readiness` prepares one exact named logical environment for later real application deployment.
+
+```text
+/deployment-readiness <environment>
+/deployment-readiness status [environment]
+```
+
+Examples include `/deployment-readiness demo`, `/deployment-readiness qa`, and `/deployment-readiness prod-east`.
+
+Production is a resolved purpose/policy classification with stronger gates, not a literal-name test. Do not silently default to Production.
+
+Logical environment purpose/role, placement, isolation, exposure, and concrete target/provider binding are separate facts.
+
+## 1. Resolve topology before machine questions
+
+Prefer the project-owned mutable topology:
+
+```text
+DEPLOYMENT_TOPOLOGY.json
+```
+
+Use `PROJECT_BOOTSTRAP.json` deployment topology only as the initial topology fallback. Do not rewrite Bootstrap provenance merely because a later environment changes.
+
+Resolve the exact configured environment name plus, when present:
+
+```text
+purpose / role
+placement
+isolation
+exposure
+binding state
+adapter
+target/provider binding
+failure domain
+```
+
+If the requested name is absent, route to `/setup` to define/configure it. Never guess a similar environment or fall back to another one.
+
+Do not assume:
+
+- a second computer exists;
+- the developer is on a trusted/home LAN;
+- Staging or Production exists;
+- Staging and Production use different physical machines;
+- deployment uses SSH;
+- a remote target exists;
+- a managed provider is supported;
+- a deferred binding is broken configuration.
+
+A custom name such as `prod-east` remains Production when its resolved purpose is Production.
+
+## 2. Reuse fresh setup-time environment proof
+
+When `/setup` already completed a disposable environment proof from this workstation for the exact environment/target and material topology/trust/platform evidence is unchanged, reuse that proof.
+
+It may establish:
+
+```text
+verified target access
+ready shared host platform
+workstation-mediated exact-image transfer
+remote application-runtime mechanics
+HTTP health verification
+disposable probe cleanup
+```
+
+It does not prove final application artifact identity, persistence/migration behavior, route/exposure, project secrets, application health contract, or release policy.
+
+If topology, target binding, host trust, platform state, or another material fact changes, treat the proof as stale and reverify the affected prerequisite.
+
+## 3. Placement branches
+
+### A. Workstation placement
+
+For a supported `workstation-container` topology, inspect local Docker/runtime, immutable application image when available, ports/health, collision ownership, persistence prerequisites, and resolved Production policy.
+
+Current reusable topology remains:
+
+```text
+placement: workstation
+isolation: container
+exposure: loopback
+```
+
+Do **not** ask for hostname, SSH user, SSH port, host keys, Caddy routes, or target profiles for a workstation environment. Current reusable workstation deployment is loopback-only and must not widen it to LAN/public exposure.
+
+A ready result may be:
+
+```text
+ENVIRONMENT READY TO DEPLOY
+
+Environment: Demo
+Purpose: demo
+Placement: workstation
+Docker: READY
+Application-specific blockers: NONE
+
+POST-DEPLOY VALIDATION PENDING
+
+NEXT
+/deploy demo
+```
+
+### B. Remote-target placement
+
+Keep these separate:
+
+```text
+named environment
+→ logical target binding
+→ current hostname or IP address
+→ SSH/deployment user
+→ independently verified host identity
+```
+
+The current address is connectivity information, not trusted identity. Preserve strict host identity verification and stop when unknown/changed host identity fails closed.
+
+Before asking questions, inspect existing non-secret profile/target evidence. Classify the workstation's target setup as `CONFIGURED`, `PARTIAL`, or `NOT CONFIGURED` and ask only for the smallest missing fact.
+
+Only after explicit `[REMOTE READ ONLY]` authorization under the installed/repository contract may new remote checks occur. Never scan/select another host or weaken host-key verification merely to get a green result.
+
+### C. Managed-service placement
+
+Use only a repository/catalog-provided provider adapter. If none exists, report:
+
+```text
+DEPLOYMENT BINDING NOT YET SUPPORTED
+Status: CATALOG GAP / PLANNED
+No provider credentials requested.
+```
+
+Do not provision infrastructure, guess a provider, or invent provider commands from general model knowledge.
+
+### D. Deferred placement
+
+Deferred placement/binding is intentional state:
+
+```text
+DEPLOYMENT INTENTIONALLY DEFERRED
+```
+
+Do not mark workspace readiness failed. Route to `/setup <environment>` or `/setup remote` if the developer later wants to bind it.
+
+## 4. Shared failure domains / colocated environments
+
+Multiple logical environments may share physical failure domains, but they remain independently targetable and independently authorized. If environments share physical failure, state it explicitly.
+
+Colocation does not demonstrate host-level Production isolation. Never infer readiness for one logical environment from another merely because they share hardware.
+
+## 5. State-driven cadence
+
+Normal cadence is:
+
+```text
+select exact project-defined environment
+→ read current topology
+→ reuse fresh environment-proof evidence when valid
+→ rediscover placement-relevant local state
+→ verify/repair only missing prerequisites under exact gates
+→ ENVIRONMENT READY TO DEPLOY
+→ /deploy <environment>
+```
+
+For remote placement, reuse valid existing target access rather than creating duplicate credentials simply because another POC/environment uses the same machine.
+
+## 6. Read-only status
+
+`/deployment-readiness status [environment]` performs no remote writes. Without a specific environment, summarize all known environments from project topology, including Placement and deferred state where evidenced.
+
+Example:
+
+```text
+Environment   Purpose      Placement      This-workstation proof   Readiness
+Demo          demo         remote-target  PROVEN                   READY
+Staging       staging      remote-target  NOT PROVEN               PARTIAL
+prod-east     production   remote-target  PROVEN                   READY
+Archive       demo         deferred       NOT APPLICABLE           DEFERRED
+```
+
+Do not manufacture target/provider facts for deferred environments.
+
+## 7. Bounded readiness writes
+
+A missing prerequisite is not authorization to change it. Use the repository/tool's exact authorization phrase for key/trust/platform/provider mutations.
+
+Do not hide the real application deployment inside readiness. Readiness may rely on the disposable setup-time proof, but it must not start/replace the real project runtime, register the final application route, perform release-specific migration, or claim project-release smoke validation.
+
+## 8. Pre-deploy versus post-deploy evidence
+
+Readiness asks whether `/deploy <name>` can safely perform the real application deployment now.
+
+Pre-deploy evidence may include topology, adapter availability, binding, local/remote identity and access, target platform, fresh proof evidence, artifact policy, route/port availability, persistence/backup/migration prerequisites, lock/recovery capability, and Production-specific safeguards.
+
+Do not require first-deployment live route, deployed-release identity, application health, or smoke evidence before the application has ever been deployed. Those are post-deploy validation evidence owned by `/deploy`.
+
+## 9. Production policy
+
+Production is logical policy, not hardware count and not the literal name `production`. A named environment such as `prod-east` with purpose `production` must retain Production readiness and later deployment gates.
+
+Readiness never authorizes Production application deployment.
+
+## 10. Final handoff
+
+When pre-deploy requirements are satisfied:
+
+```text
+ENVIRONMENT READY TO DEPLOY
+
+Environment: <exact name>
+Purpose: <purpose>
+Placement: <...>
+Binding: VERIFIED / LOCAL / provider-specific
+This-workstation environment proof: PROVEN / NOT REQUIRED / NOT AVAILABLE
+Platform prerequisites: READY
+Application-specific prerequisites: READY / <remaining items>
+Security blockers: NONE
+
+POST-DEPLOY VALIDATION PENDING
+
+NEXT
+/deploy <exact-name>
+```
+
+This is evidence, not deployment authorization. `/deploy` owns the real application write gate for the exact named environment, resolved Production classification, placement, target/provider, artifact, and current evidence.

package/assets/generated/core/core/skills/developer-env-mode/SKILL.md

@@ -0,0 +1,231 @@
+---
+name: developer-env-mode
+description: "Converge and verify the developer workstation for local-only or remote-enabled work. Mode changes become effective only after the selected readiness contract passes."
+argument-hint: "status|local|remote"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Developer Environment Mode
+
+`/developer-env-mode` manages the current workstation's operational development mode. It is not a deployment command and it does not weaken Staging or Production gates.
+
+Supported intents:
+
+```text
+/developer-env-mode status
+/developer-env-mode local
+/developer-env-mode remote
+```
+
+The governing invariant is:
+
+```text
+MODE != preference
+MODE = verified operational state
+```
+
+Never record a requested mode as ready until its readiness contract passes. If convergence fails, preserve the prior ready mode when one exists and report the blocker.
+
+## 1. Resolve repository and package provenance read-only
+
+From the repository root inspect, when present:
+
+- `PROJECT_BOOTSTRAP.json`;
+- `PROJECT_FORGE_BASELINE.json` and component baselines;
+- `DEV_ENVIRONMENT.json`;
+- application setup/build/test commands and project-owned persistence configuration;
+- deployment topology and generated deployment tooling;
+- Git status so unrelated work is preserved.
+
+For package-managed consumers, verify managed files are coherent before relying on distributed Core or Deployment tooling. Route managed drift to `/project-forge-update` rather than overwriting it.
+
+Do not require a Bootstrap/Core/Deployment Kit source checkout for normal consumer use.
+
+## 2. Keep current mode state workstation-local
+
+Mode state is user/workstation state, not repository authority. Store it outside the repository under the user-scoped Project Forge directory, using a repository-scoped location such as:
+
+```text
+~/.project-forge/workspaces/<owner>/<repo>/developer-environment.json
+```
+
+Do not commit this state. Do not store credentials, private keys, target trust stores, database contents, or secret values in it.
+
+Record enough non-secret evidence to distinguish requested mode from readiness, for example:
+
+- mode;
+- ready/not-ready;
+- verification timestamp;
+- source revision when available;
+- build/test state or fingerprint;
+- local database state when applicable;
+- local runtime health when applicable;
+- remote target/access readiness summary when applicable.
+
+A later `status` check must be allowed to report that the recorded mode is no longer ready when Docker stops, tools drift, the build becomes stale, the local database is missing/incompatible, or remote access disappears.
+
+## 3. `status` is read-only
+
+`/developer-env-mode status` performs no setup writes. Inspect current workstation evidence and live prerequisites, then report both the selected mode and current readiness.
+
+Prefer a compact result such as:
+
+```text
+DEVELOPER ENVIRONMENT
+
+Selected mode: LOCAL
+Readiness: NOT READY
+
+Docker ........ READY
+Build ......... STALE
+Tests ......... READY
+SQLite ........ READY
+Runtime ....... HEALTHY
+Remote access . UNAVAILABLE
+
+NEXT
+/developer-env-mode local
+```
+
+Do not silently repair state during `status`.
+
+## 4. `local` means converge a complete local development environment
+
+Selecting `local` authorizes bounded, non-destructive workstation setup needed to make the current repository usable locally. It does not authorize destructive database reset, deletion of unrelated Docker state, remote publication, remote deployment, or Production writes.
+
+Converge in this order.
+
+### A. Workstation prerequisites
+
+Verify the current OS is supported by repository configuration. Use repository setup/doctor tooling when present to verify required tools and versions.
+
+For Docker-based local execution require a working Docker CLI/engine. Prefer repository-distributed Deployment Kit commands when `DEPLOYMENT_BASELINE.json` proves they are installed.
+
+### B. Dependencies and restore
+
+Run repository-defined dependency restore/setup commands when missing or stale. Preserve pinned versions and project conventions. Do not substitute arbitrary global tooling when the repository defines a supported path.
+
+### C. Local persistence
+
+If the application uses SQLite for local development:
+
+1. resolve the project-owned database filename/container path and migration/initialization contract from repository configuration/docs/code;
+2. prefer the installed Deployment Kit local SQLite ensure/status primitive when available for workstation-owned persistent storage;
+3. when the database is absent, create the owned local SQLite file/directory non-destructively;
+4. run the repository-provided migration/schema initialization needed to make that database usable;
+5. verify the resulting database can be opened and that the application-required schema/migration state is current when the repository provides such a check.
+
+If an existing SQLite database is corrupt, incompatible, or has unexpected ownership/schema state, **STOP**. Never delete, replace, reset, or migrate destructively merely to make mode convergence pass. Present the exact recovery/reset decision separately.
+
+Do not assume every project uses SQLite. Other persistence requires an explicit repository-owned local setup contract.
+
+### D. Build and tests
+
+Run the repository's required local build and test commands. A missing or stale build is a normal convergence condition; rebuild it.
+
+If build or required tests fail, report `LOCAL MODE NOT READY` and do not mark the mode ready.
+
+When the project policy says application validation is local-only, GitHub publication/PR activity does not replace this local build/test evidence.
+
+### E. Local immutable Docker artifact
+
+When the local runtime is Docker-based, build the application image locally using repository-owned commands. Resolve an immutable local image identity.
+
+The standard Deployment Kit workstation adapter may accept either:
+
+- an exact registry digest (`name@sha256:...`), or
+- a local Docker image ID (`sha256:<64 hex>`) for workstation-only execution.
+
+Never use a mutable tag as the final deployed identity. A local image ID is valid only for workstation placement and is not remote-release evidence.
+
+### F. Workstation runtime
+
+Converge the local application runtime through the repository-distributed workstation adapter when available:
+
+```text
+placement: workstation
+isolation: container
+exposure: loopback
+```
+
+Keep exposure loopback-only. Mount the project-owned local SQLite persistence directory when required. Verify the declared health endpoint and any required local smoke check.
+
+Do not resolve SSH targets, publish images, create public routes, or deploy Staging/Production while entering local mode.
+
+### G. Commit local mode only after readiness passes
+
+Only after prerequisites, persistence, build, tests, runtime, and health requirements pass, write the workstation-local mode state as ready.
+
+A successful summary should distinguish local evidence from remote evidence:
+
+```text
+LOCAL DEVELOPER ENVIRONMENT READY
+
+Build ........ READY
+Tests ........ READY
+Docker ....... READY
+SQLite ....... READY / NOT APPLICABLE
+Application .. HEALTHY
+Remote deploy. DISABLED BY MODE
+```
+
+## 5. `remote` means verify remote-enabled capability, not deploy
+
+Selecting `remote` authorizes bounded, non-destructive checks/setup needed to prove that the current workstation can work with the repository's configured remote non-Production environment(s). It does **not** publish an artifact or deploy an application.
+
+Verify as applicable:
+
+- normal local developer prerequisites still needed to build/test the project;
+- repository deployment topology contains a non-deferred remote environment;
+- exact target/provider binding exists when required;
+- workstation-to-target trust/access is valid;
+- target OS/runtime/platform readiness is valid;
+- persistence/readiness prerequisites can be inspected safely;
+- GitHub/registry access needed for a later release/publish step is available;
+- repository release/deployment tooling and baselines are coherent.
+
+For the standard remote-SSH path preserve strict host identity. Unknown or changed host identity is a stop condition. Never fall back to another environment or host.
+
+Do not require a Production target merely to enter remote mode. Do not weaken Production authorization because remote mode is ready.
+
+Only after the selected remote readiness checks pass, record `remote` as ready.
+
+Then report the next explicit operation, typically:
+
+```text
+/deployment-readiness <environment>
+```
+
+A later `/deploy <environment>` remains separately gated.
+
+## 6. Fail closed on destructive or ambiguous repair
+
+Automatic convergence may safely create missing local directories, dependency caches, build outputs, a new owned SQLite file, migrations that the project defines as normal forward initialization, and a new owned local application container.
+
+Stop for a separate explicit decision before:
+
+- deleting/resetting an existing database;
+- destructive migration or rollback;
+- replacing unexplained persistent data;
+- deleting unrelated containers/images/volumes;
+- publishing an artifact remotely;
+- rebinding a target;
+- weakening host verification;
+- deploying Staging or Production;
+- changing public/LAN exposure.
+
+## 7. Relationship to other Project Forge commands
+
+`/developer-env-mode` prepares a workstation and establishes current operational readiness.
+
+It does not replace:
+
+- `/project-forge-update` for managed Project Forge package changes;
+- project setup/doctor tooling;
+- `/start-work` for implementation authorization;
+- `/deployment-readiness` for environment-specific pre-deploy evidence;
+- `/deploy` for deployment authorization/execution;
+- `/tear-down` for destructive cleanup.
+
+Mode switching never implies merge, release publication, Staging deployment, or Production deployment.

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

@@ -0,0 +1,116 @@
+---
+name: docs
+description: "Open or inspect the repository's current Project Forge 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/project-forge-docs.json` when present.
+2. Verify the documentation viewer exists at `tools/project-forge-docs/docs-site.py`.
+3. If it exists, use the repository-local Python/runtime convention to run:
+
+```text
+python tools/project-forge-docs/docs-site.py serve --root .
+```
+
+The viewer binds to loopback only and writes disposable output under `.project-forge/`.
+
+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/project-forge-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 Project Forge-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/project-forge-docs/docs-site.py build --root . --out .project-forge/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/project-forge-docs.json`:
+
+- `project` — project-owned prose and ADRs;
+- `project-forge` — 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/grill-me/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: grill-me
+description: Continuously challenge requirements, architecture, plans, implementation assumptions, or work-item coverage without editing files.
+argument-hint: "<work-item ID, external key, document, plan, or topic>"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Grill Me
+
+Purpose: improve reasoning by challenging the highest-value uncertainty without adding process overhead.
+
+## Rules
+
+- Read `.github/project-forge-workspace.json` when present and only the minimum relevant context.
+- Ask one material question at a time.
+- Explain briefly why the question matters.
+- Challenge vague answers, hidden scope, contradictions, and weak assumptions.
+- Recommend an answer or 2–3 options with tradeoffs when useful.
+- Do not edit files.
+- Do not invoke subagents.
+- Do not create artifacts merely because grilling occurred.
+- Do not claim external Jira/Issue content was read unless it was actually available.
+
+Challenge areas may include:
+- missing acceptance behavior,
+- cross-work-item/Epic gaps,
+- domain/business rules,
+- lifecycle/state transitions,
+- validation/failure behavior,
+- data integrity,
+- concurrency/transactions,
+- destructive/reversible actions,
+- architecture assumptions,
+- security/operational risk,
+- testability.
+
+## Cadence
+
+```text
+QUESTION
+<one focused question>
+
+WHY IT MATTERS
+<short explanation>
+
+RECOMMENDATION
+<recommended answer/options when useful>
+```
+
+After the human answers:
+
+```text
+analyze/challenge the answer
+→ explain implications when useful
+→ ask the next material question
+```
+
+Do not ask `Do you want to continue?` after each answer. The human already entered a continuous grilling mode.
+
+Stop only when:
+- the human says stop/done/pause,
+- no material issues remain,
+- a true scope/decision/action gate appears,
+- the human switches workflow.
+
+## Natural completion
+
+Summarize once:
+- decisions strengthened,
+- unresolved issues,
+- recommended next workflow.
+
+Typical next workflows:
+- `/grill-with-docs` to reconcile resolved decisions,
+- `/refine-requirements` for systematic detailed coverage,
+- `/start-work` when the item is ready.