@mriekki/lean 0.4.3 → 0.4.5

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

@@ -1,6 +1,6 @@
 ---
 name: deploy
-description: "Guided deployment orchestration for a configured named environment. Verifies pre-deploy readiness, selects the exact target/artifact, preserves tool-specific authorization, delegates deterministic execution, and validates the resulting live deployment."
+description: "Guided deployment orchestration for a named logical environment. Verifies topology/readiness, selects the exact placement/target/artifact, preserves tool-specific authorization, delegates deterministic execution, and validates resulting evidence."
 argument-hint: "[environment] [release-or-artifact]"
 user-invocable: true
 disable-model-invocation: true
@@ -8,28 +8,34 @@ disable-model-invocation: true
 
 # Deploy
 
-`/deploy` is the normal human-facing deployment interface once deployment engineering is delivered and the selected environment is **ready to deploy**.
+`/deploy` is the human-facing deployment interface once the selected logical environment is ready to deploy.
 
-Core owns interaction, validation, target safety, Human-in-the-Loop authorization, and evidence-oriented orchestration. Repository-provided deployment tooling owns deployment mechanics.
+Core owns interaction, validation, topology safety, Human-in-the-Loop authorization, and evidence-oriented orchestration. Repository-provided deployment tooling owns mechanics.
 
-Do not implement Docker, SSH, route, migration, or application deployment logic directly in this skill when an approved repository command exists.
+Do not implement Docker, SSH, provider API, route, migration, or application deployment logic directly in this skill when an approved repository command exists.
 
-## 1. Begin read-only and establish provenance
-
-Invocation starts read-only.
+## 1. Begin read-only and resolve provenance/topology
 
 Read only the minimum repository context needed to identify:
 
-- `LEAN_BASELINE.json` when the repository is package-managed;
-- `DEPLOYMENT_BASELINE.json` when present;
+- `POC_BOOTSTRAP.json` deployment topology when present;
+- `LEAN_BASELINE.json` / `DEPLOYMENT_BASELINE.json` when package-managed;
 - approved deployment/release requirements;
-- configured named environments and checkout-local target bindings;
-- selected environment pre-deploy readiness evidence;
-- approved release/artifact policy;
-- repository-provided deployment entry point and its authorization contract;
-- expected developer-workstation and target operating systems.
-
-Do not assume configuration filenames, target OS, SSH aliases, container runtime, or release format unless the repository establishes them.
+- configured named environments and their role/purpose;
+- selected environment placement, isolation, exposure, binding state, adapter, failure domain;
+- selected environment readiness evidence;
+- approved artifact/release policy;
+- repository-provided deployment entry point and exact authorization contract.
+
+Do not assume:
+
+- deployment means remote SSH;
+- a second computer exists;
+- a home/trusted LAN exists;
+- Staging or Production exists;
+- Staging and Production use separate machines;
+- a managed provider is supported;
+- a deferred environment is an error.
 
 When `DEPLOYMENT_BASELINE.json` identifies the standard Lean POC Deployment Kit and its generated entry point exists, prefer the repository-distributed interface such as:
 
@@ -37,187 +43,223 @@ When `DEPLOYMENT_BASELINE.json` identifies the standard Lean POC Deployment Kit
 tools/lean-deployment/lean-poc-deploy.py
 ```
 
-over reconstructing Deployment Kit commands by hand or requiring a separate Kit checkout.
+Do not require a separate Deployment Kit checkout.
 
-If package/component baseline integrity is known to be drifted, deployment engineering is incomplete, or a selected environment has unresolved **pre-deploy** blockers, stop and route to `/lean-update`, `/upstream-fix`, the deployment work item, or `/deployment-readiness <environment>` as appropriate.
+If package/component managed files are drifted or the selected environment has unresolved pre-deploy blockers, stop and route to `/lean-update`, `/upstream-fix`, the deployment work item, or `/deployment-readiness <environment>`.
 
-Do not block a first deployment merely because live route resolution, application health, smoke results, deployed-release identity, or release-specific rollback evidence do not exist yet. Those are produced by this deployment flow.
+## 2. Select one logical environment explicitly
 
-## 2. Select an environment explicitly
+If no environment is named, enumerate repository-defined environments and ask the human to select one.
 
-If the invocation did not name an environment, enumerate only environments configured for this checkout and ask the human to select one.
+Rules:
 
-Show enough non-secret identity to distinguish them.
+- never silently default to Production;
+- never reuse a remembered prior selection as Production authorization;
+- never fall back to another environment/placement/host/provider because deployment fails;
+- environment selection chooses scope but never authorizes the write.
 
-Rules:
+If the selected environment is explicitly deferred, do not call that an invalid repository state. Report:
+
+```text
+DEPLOYMENT NOT BOUND YET
+
+Environment: <name>
+Placement: DEFERRED
+
+This POC can continue development/CI/docs/learning, but there is no current deployment executor for this environment.
+
+NEXT
+/deployment-readiness <environment>
+```
+
+Do not provision or guess infrastructure inside `/deploy`.
+
+## 3. Branch by placement/adapter
 
-- never silently default to `production`;
-- never use a remembered prior selection as implicit production authorization;
-- never fall back from one environment to another because discovery, access, readiness, or deployment failed;
-- if a named environment is not configured, fail explicitly and route to `/deployment-readiness <environment>`;
-- selecting an environment chooses scope but does not authorize the deployment write.
+### A. Workstation container
 
-## 3. Resolve and verify the machine/target binding
+For a current reusable topology such as:
+
+```text
+placement: workstation
+isolation: container
+exposure: loopback
+adapter: workstation-container
+```
 
-Keep the human-facing identity simple while preserving the stronger internal model:
+use the repository-distributed local deployment command, for example:
+
+```text
+lean-poc-deploy local ...
+```
+
+Verify placement-relevant facts only:
+
+- current workstation Docker/runtime availability/readiness evidence;
+- exact immutable image/artifact;
+- selected local environment identity;
+- host/runtime port and health path when owned by project configuration;
+- local Lean ownership/port collision plan;
+- persistence requirements when applicable;
+- Production policy when this logical environment is Production.
+
+Do **not** resolve SSH hostnames, target profiles, host keys, Caddy routes, or remote OS for a workstation environment.
+
+Current reusable workstation-container support is loopback-only. Do not widen to `0.0.0.0`, LAN, tunnel, or public exposure as an implicit convenience. A shareable/public outcome needs another supported placement/adapter.
+
+### B. Remote target
+
+For a remote target, preserve the strict machine/identity model:
 
 ```text
 named environment
-→ confirmed machine hostname/address
-→ configured target/profile binding
-→ current address discovery
+→ explicit logical target binding
+→ current address/discovery
 → independently verified host identity
 ```
 
-Address discovery is not host trust.
+Before deployment:
 
-Before remote deployment:
-
-- verify the selected environment resolves to the configured machine/target established by readiness;
-- show the confirmed hostname/address when appropriate rather than asking the human to reconstruct an internal `targetName`;
-- use the repository-approved stable internal target/profile rather than a guessed transient address;
-- preserve enrolled host-key verification independently of current IP;
+- verify the environment resolves to the exact target established by readiness;
+- show the confirmed hostname/address when helpful instead of forcing an internal `targetName` on the user;
+- preserve strict independently verified host trust;
 - stop on unknown/changed host identity;
-- never bypass host-key checks, silently enroll new trust, scan/select another host, or weaken network controls as recovery;
-- verify actual target OS compatibility before target-specific behavior.
+- never scan/select another host, bypass host-key checks, or weaken network controls as recovery;
+- verify target OS/runtime compatibility required by the installed adapter.
+
+A single physical target may host multiple logical environments. Keep their runtime/container, route, data, evidence, and authorization scopes distinct.
+
+When the selected environment shares a physical `failureDomain` with another environment, surface that fact before the write. If Production is involved, say explicitly that host-level Production isolation is not demonstrated.
+
+Trusted-LAN `.local` routing conventions apply only when the selected repository topology/adapter uses them. Do not project home-LAN assumptions onto public VPS, VPN/private, or other remote topologies.
+
+### C. Managed service
 
-Changing an environment's machine/target binding is readiness/configuration work, not deployment fallback.
+Use only a repository/catalog-provided provider adapter.
 
-Keep private keys, passphrases, credentials, copied trust databases, and other secret values out of repository configuration and logs.
+If no implemented adapter exists, stop with `CATALOG GAP / PLANNED` rather than constructing provider commands from model knowledge.
+
+Never ask for or store provider credentials unless the installed adapter defines the exact credential boundary and readiness/deployment contract.
 
 ## 4. Resolve the repository-provided launcher
 
-Prefer the canonical repository-provided deployment interface established by the current deployment baseline.
+Prefer the canonical deployment interface established by current baselines/configuration.
 
-For package-generated Deployment Kit consumers this normally means the generated Python entry point plus its distributed modules. Do not require a sibling Deployment Kit clone for normal deployment.
+Launcher choice depends on placement/adapter:
 
-A repository may additionally provide PowerShell/shell wrappers. Use them only when the repository defines them as the approved interface or when they intentionally wrap the same deterministic contract.
+- workstation-container → repository-distributed local adapter;
+- remote-target → repository-distributed remote adapter;
+- managed-service → provider-specific adapter only when actually installed/supported;
+- deferred → no launcher; route back to readiness.
 
-Launcher choice may depend on developer workstation OS; target behavior depends on selected target OS. Do not confuse those dimensions.
+PowerShell/shell wrappers are acceptable only when the repository defines them as the approved front end to the same deterministic contract.
 
-If the approved launcher is absent, locally drifted, or unsupported on the current workstation/target, stop rather than inventing deployment mechanics.
+If the approved launcher is absent, drifted, or unsupported on the current workstation/placement, stop rather than inventing mechanics.
 
-## 5. Resolve release/artifact identity
+## 5. Resolve exact artifact identity
 
-Use the repository's approved policy for the selected environment.
+Use repository-approved policy for the selected logical environment.
 
-For production require the approved formal release/artifact evidence, including immutable identity when required.
+For Production require the approved formal immutable release/artifact evidence when the project requires it.
 
-For non-production, use only the broader artifact policy explicitly allowed by the repository. Do not invent relaxed staging semantics.
+For non-Production, use only broader artifact policy explicitly allowed by the repository. Do not invent relaxed Staging/Demo semantics.
 
-When promoting a tested artifact to production, prefer the exact same immutable artifact/digest rather than rebuilding it.
+When promoting across environments, prefer the exact same immutable artifact/digest where the repository's promotion policy requires or recommends that.
 
-If readiness was completed before the final release/artifact existed, re-check the selected artifact and any artifact-specific pre-deploy prerequisites now. Do not force a separate readiness ceremony when the remaining check can be performed read-only and the environment facts have not materially changed.
+If readiness preceded the final artifact, re-check artifact-specific prerequisites now when read-only checks are sufficient. Do not force a ceremonial readiness rerun when topology facts are unchanged.
 
-## 6. Build the deterministic deployment plan
+## 6. Build the deterministic plan
 
-Use repository-provided tooling to construct or inspect the exact plan when supported.
+Use repository-provided tooling to construct/inspect the exact plan when supported.
 
-The plan may include, according to the repository contract:
+The plan may include only operations defined by the selected adapter/repository, for example:
 
 ```text
-pre-deploy backup or safety check
+optional backup/safety check
 → release-specific migration
 → application/container deployment
-→ application route registration/update
+→ route or loopback-port publication
 → health/readiness verification
 → smoke validation
 → deployment evidence capture
 ```
 
-Do not add operations the repository/tool does not define.
-
-Route registration, migration, and other application/release-specific writes are deployment operations when they are part of the repository's deterministic deployment contract. They are not hidden `/deployment-readiness` side effects.
+Placement changes which operations are meaningful. A workstation loopback deployment does not need Caddy/SSH; a remote route deployment may.
 
-Application rollback execution, database restore/destructive recovery, target rebinding, unrelated host provisioning, and environment tear-down remain separate decisions unless the approved deployment contract explicitly defines a safe bounded automatic rollback for the failed deployment itself.
+Application rollback execution, database restore/destructive recovery, target/provider rebinding, unrelated provisioning, and environment tear-down remain separate decisions unless the installed deterministic deployment contract explicitly includes a bounded safe rollback for the failed deployment itself.
 
-## 7. Preserve the deployment tool's exact authorization contract
+## 7. Preserve exact authorization contracts
 
-Core may describe consequence classes using labels such as `[REMOTE WRITE]` and `[PRODUCTION WRITE]`, but those labels do not replace a stricter exact authorization phrase required by the repository-provided deployment tool.
+Core consequence labels do not replace stricter installed-tool phrases.
 
-For example, the standard Deployment Kit may require operation-specific phrases such as:
+Examples the standard Deployment Kit may require include:
 
 ```text
+[LOCAL APP DEPLOY]
 [APP DEPLOY WRITE]
 [PRODUCTION APP DEPLOY]
 ```
 
-The exact phrase must be resolved from the installed repository/tool contract. Do not hardcode an example phrase when the installed version requires a different one.
+Resolve the exact phrase from the installed tool/version. Do not hardcode an example when the installed contract differs.
 
-Authorization applies only to the exact environment, verified target, artifact, plan/evidence, and operation shown. If any materially changes, stop and require renewed review/authorization.
+Authorization applies only to the exact logical environment, placement/target/provider, artifact, reviewed plan/evidence, and operation shown. Any material change requires renewed review/authorization.
 
-No requirements approval, code review, PR merge, CI pass, environment selection, prior deployment, or readiness result implicitly authorizes a deployment write.
+Production remains Production regardless of physical placement. A Production container on a shared VPS or workstation still requires the Production deployment gate; topology limitations are additional evidence, not a reason to weaken it.
 
-## 8. Present the deployment preview and gate
+## 8. Present a topology-aware preview
 
-Before the modifying command show the resolved non-secret facts:
+Before the modifying command show non-secret facts appropriate to the placement:
 
 ```text
 DEPLOYMENT READY
 
 Environment: <name>
-Role: <production|non-production>
-Machine: <confirmed hostname/address>
-Target OS: <verified>
+Role/Purpose: <...>
+Placement: <workstation|remote-target|managed-service>
+Isolation: <...>
+Exposure: <...>
+Failure domain: <known value / not recorded>
+Target/Machine/Provider: <only when applicable>
 Launcher: <repository-provided command>
 Deployment baseline: <exact commit/distribution when present>
 Release/artifact: <verified immutable identity>
-Pre-deploy readiness blockers: NONE
-Planned deployment operations: <repository/tool-defined summary>
-Required authorization: <exact tool phrase or repository gate>
-Post-deploy validation: route/health/smoke/evidence checks that will run after the write
+Pre-deploy blockers: NONE
+Planned operations: <tool-defined summary>
+Required authorization: <exact installed phrase>
+Post-deploy validation: <placement-relevant health/route/smoke/evidence>
 ```
 
-Include an internal target/profile label only when it materially helps disambiguate the exact machine or tool plan. Do not make that identifier the primary human-facing identity.
-
-For a non-production deployment ask for one bounded authorization covering the exact reviewed plan and required tool phrase.
+For workstation placement, replace Machine/Target OS with local Docker/loopback facts; do not display fake remote fields.
 
-For production require the project's explicit production deployment gate and the exact installed tool phrase. Keep the consequence visible as:
+For colocated environments include the shared-failure-domain warning in the preview.
 
-```text
-[PRODUCTION WRITE]
-```
+For Production include `[PRODUCTION WRITE]` consequence visibility plus the exact installed Production phrase.
 
-Do not translate a generic `approve` into a broader tool-specific phrase unless the user clearly authorized the exact reviewed deployment operation represented by that phrase.
-
-## 9. Execute only the approved script contract
+## 9. Execute only the approved deterministic contract
 
 After authorization invoke only the repository-provided launcher with the explicitly selected environment and approved artifact inputs.
 
-Do not perform unrelated host provisioning, target rebinding, firewall changes, credential creation, destructive recovery, database restore, or other out-of-band writes as part of `/deploy` unless they are explicitly inside the reviewed deterministic deployment contract.
-
-If the script reports missing prerequisites, identity mismatch, unexpected target OS, lock contention, migration failure, readiness failure, stale plan/evidence, or another blocker, stop according to the repository contract. Never redirect to another environment or host.
-
-If a failure occurs after a partial deployment, use only repository/tool-defined safe failure handling. Do not improvise destructive rollback or database recovery.
-
-## 10. Verify live deployment and record outcome
+Do not perform unrelated provisioning, target rebinding, firewall changes, credential creation, exposure widening, destructive recovery, restore, or environment tear-down unless those are explicitly inside the reviewed deterministic contract.
 
-After execution, use repository-provided inventory, route, readiness, health, smoke, and evidence commands when available.
+If the tool reports missing prerequisites, identity mismatch, port/route collision, unsupported placement, lock contention, migration failure, readiness failure, stale evidence, or another blocker, stop. Never redirect to another environment, host, provider, or wider exposure.
 
-For a first deployment, this is where evidence such as the following becomes meaningful:
+## 10. Validate live evidence
 
-- application route registration and client-resolvable route behavior when verifiable from the approved surface;
-- exact deployed release/artifact identity;
-- container/process running state;
-- application readiness/health result;
-- smoke-test result;
-- release-specific migration outcome;
-- deployment evidence/current-release identity;
-- rollback/recovery compatibility evidence when the repository contract can establish it non-destructively.
+After execution, use repository-provided inventory/health/route/smoke/evidence commands when available.
 
-Report only evidence-backed outcomes:
+Placement-relevant evidence may include:
 
-- selected environment;
-- verified machine/target identity;
-- deployment baseline/tool identity when relevant;
-- release/artifact identity;
-- deployment result;
-- route result when applicable;
-- readiness/health/smoke result;
-- migration result when applicable;
-- rollback/recovery capability/evidence when applicable.
+- exact deployed artifact identity;
+- application container/process running state;
+- loopback health for workstation deployment;
+- remote route registration/resolution when applicable;
+- application readiness/health;
+- smoke result;
+- migration result;
+- current release/deployment evidence;
+- safe rollback/recovery compatibility evidence when the installed contract can establish it non-destructively.
 
-Do not report success merely because a command returned or a container/process started if stronger readiness evidence is required.
+Do not report success merely because a command returned or a container started if stronger health evidence is required.
 
 A successful deployment may be summarized as:
 
@@ -225,13 +267,14 @@ A successful deployment may be summarized as:
 DEPLOYMENT VALIDATED
 
 Environment: <name>
+Placement: <...>
 Artifact: <exact immutable identity>
-Route: READY / NOT APPLICABLE
+Endpoint/Route: READY / LOOPBACK / NOT APPLICABLE
 Application health: READY
-Smoke: PASSED
+Smoke: PASSED / NOT REQUIRED
 Deployment evidence: RECORDED / VERIFIED
 ```
 
-For a Staging-to-Production promotion flow, the repository may require a human Staging validation/attestation after this technical validation. That validation is evidence for later Production promotion; it does not itself authorize Production deployment.
+For a Staging-to-Production flow, human Staging validation may be evidence for later promotion; it never authorizes Production deployment.
 
-Application rollback execution, database restore/destructive recovery, and environment tear-down remain separate decisions when the repository contract makes them separate.
+Rollback execution, destructive database restore/recovery, and tear-down remain separate when the repository contract keeps them separate.