@mriekki/lean 0.3.2 → 0.4.0

package/assets/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@mriekki/lean",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "defaultProfile": "greenfield-poc",
   "profiles": {
     "greenfield-poc": {
@@ -14,8 +14,8 @@
   "components": {
     "core": {
       "repository": "mriekki/lean-agentic-core",
-      "commit": "bcc3836b50713504aea1dc47b8ad26bf483315dd",
-      "version": "1.12.1",
+      "commit": "7d6b6ce00d83063775d7491626fe6b253b9c51c8",
+      "version": "1.13.0",
       "distribution": "greenfield-workspace",
       "descriptor": "assets/core/distribution.json",
       "sourceRoot": "assets/generated/core",

package/assets/generated/ASSEMBLY.json

@@ -1,12 +1,12 @@
 {
   "schemaVersion": 1,
   "package": "@mriekki/lean",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "components": {
     "core": {
       "repository": "mriekki/lean-agentic-core",
-      "commit": "bcc3836b50713504aea1dc47b8ad26bf483315dd",
-      "version": "1.12.1",
+      "commit": "7d6b6ce00d83063775d7491626fe6b253b9c51c8",
+      "version": "1.13.0",
       "distribution": "greenfield-workspace",
       "files": [
         {
@@ -17,7 +17,7 @@
         {
           "source": "core/agents/reviewer.agent.md",
           "destination": ".github/agents/reviewer.agent.md",
-          "sha256": "c999281aeab6fd17ea308d581a7e931a06d7b93f33871915605956643c7b22ff"
+          "sha256": "2534ef7f1001da725a503874859c84945586c4f2aed9aec0fe3e04bc24de14c3"
         },
         {
           "source": "core/agents/coach.agent.md",
@@ -57,17 +57,17 @@
         {
           "source": "core/skills/start-work/SKILL.md",
           "destination": ".github/skills/start-work/SKILL.md",
-          "sha256": "43c10278bd715ec95f3aa8d4ed4a2a4b51aa9fc6484e1fda572037381e663de4"
+          "sha256": "4d2805305424942c8aa7184d82578e59af1785cfd5b89c9d7314f3a1ffef4027"
         },
         {
           "source": "core/skills/next-step/SKILL.md",
           "destination": ".github/skills/next-step/SKILL.md",
-          "sha256": "0fac7b36f62039341c7536ff1516387efd4b6b32885dceb58d59510480ff9d6b"
+          "sha256": "6fb5275cc098f3124c85bb20ccf713affac23ebd5b96962558504936f2b891d4"
         },
         {
           "source": "core/skills/deliver/SKILL.md",
           "destination": ".github/skills/deliver/SKILL.md",
-          "sha256": "bb31e292a57372c6f64f627035652632b474f1ebcaab604eded57d730825af8a"
+          "sha256": "2c97f86bedf4baf1fb287cdc7b509975bd556861e9739713db85f1c5ee87c6eb"
         },
         {
           "source": "core/skills/cleanup-branches/SKILL.md",
@@ -102,12 +102,12 @@
         {
           "source": "core/skills/deployment-readiness/SKILL.md",
           "destination": ".github/skills/deployment-readiness/SKILL.md",
-          "sha256": "5e4f50c9ab696b16e677fc6e4be3f581ac912e7b15c077b376457d00c01c1623"
+          "sha256": "02a58ae52cab8b6b11734a8d4217bf7f7c9b11bcd7b35e4a2e16dfb8af8bce34"
         },
         {
           "source": "core/skills/deploy/SKILL.md",
           "destination": ".github/skills/deploy/SKILL.md",
-          "sha256": "e34b29d3d19945b6317adb9e5796895dc75f249015ec9708fd256ab7e0ca0c5f"
+          "sha256": "259c0091672d79b7bc799f92cb21a4143af2951a4f2556794263237dfb7e7d7b"
         },
         {
           "source": "core/skills/tear-down/SKILL.md",
@@ -142,7 +142,7 @@
         {
           "source": "core/process/DEPLOYMENT_ENABLEMENT.md",
           "destination": "docs/process/DEPLOYMENT_ENABLEMENT.md",
-          "sha256": "a57819ce9e52227df8260d789fb6911721aac0e391a53e711fbb27d7a17b3245"
+          "sha256": "3b59c5984ecb51ac48efb40e7e2e24c1971db947d6eefa5dc3671254ca984af7"
         },
         {
           "source": "core/process/HUMAN_GATES.md",

package/assets/generated/core/core/agents/reviewer.agent.md

@@ -82,4 +82,4 @@ When implementation is READY and the human accepts the meaningful local diff, ex
 
 Do not vaguely say `merge when ready`.
 
-If the delivered work item owns deployment engineering, successful engineering delivery may later hand off to `/deployment-readiness <deployment-enabler-ID> enable [environment]`; Reviewer readiness never authorizes remote or production deployment.
+If the delivered work item owns deployment engineering, successful engineering delivery may later hand off to `/deployment-readiness <environment>` for state-driven environment preparation; Reviewer readiness never authorizes remote or production deployment.

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

@@ -4,28 +4,24 @@ Deployment enablement is the guided operational lane between delivered deploymen
 
 A repository may have multiple named deployment environments, such as Staging and Production. Each environment owns its own confirmed machine/target binding, readiness evidence, data/backup state, credentials, and deployment policy.
 
-Use:
+The normal human-facing entry point is state-driven:
 
 ```text
-/deployment-readiness [deployment-enabler-ID] discovery [environment]
+/deployment-readiness <environment>
 ```
 
-to discover environment setup early, and:
-
-```text
-/deployment-readiness [deployment-enabler-ID] enable [environment]
-```
-
-after deployment engineering is reviewed, delivered, merged, and applicable default-branch CI/policy evidence is satisfactory.
+The workflow discovers current state and continues from the furthest safe point. The human does not need to choose separate `discovery`, `enable`, or `resume` modes.
 
 For a read-only local overview use:
 
 ```text
-/deployment-readiness [deployment-enabler-ID] status [environment]
+/deployment-readiness status [environment]
 ```
 
 Omit the environment from `status` to summarize all configured named environments without automatically probing every remote machine.
 
+Older invocations that include a deployment-enabler ID and/or `discovery`, `enable`, or `resume` may be normalized for compatibility, but they are not the normal interface.
+
 ## Human-facing readiness model
 
 The workflow should ask about simple environment-machine facts before exposing deployment-tool internals.
@@ -46,7 +42,7 @@ If setup is partial, show what is known and ask only for the smallest missing fa
 
 If setup is absent, start with the selected machine's hostname or IP address, then ask one additional simple fact at a time only when required.
 
-## Discover, confirm, verify
+## Discover, confirm, verify, continue
 
 Normal readiness cadence is:
 
@@ -58,15 +54,54 @@ select environment
 → authorize read-only connectivity/identity verification
 → run repository/Deployment-Kit doctor/verify checks
 → reuse working access OR repair only missing setup OR onboard a new workstation
-→ verify remaining runtime/security/data/release prerequisites
-→ environment READY
+→ verify target/platform/security/artifact/registry/data prerequisites
+→ ENVIRONMENT READY TO DEPLOY
 → /deploy <environment>
 ```
 
+The next readiness invocation re-discovers current state and resumes automatically. It does not require a new mode word after discovery or repair.
+
 Remote probing does not occur merely to build the initial local summary.
 
 Address discovery is not host trust. When SSH is used, unknown or changed host identity stops access; readiness must not recover by disabling host-key verification, silently enrolling new trust, scanning/selecting another host, weakening network controls, or redirecting to another environment.
 
+## Readiness writes versus deployment writes
+
+Readiness may perform bounded prerequisite/setup writes when separately authorized and supported by repository tooling, such as:
+
+- local environment binding;
+- key/agent/trust setup;
+- target-side access setup;
+- runtime/platform prerequisite setup;
+- data/backup directory preparation;
+- firewall preparation;
+- registry credential setup.
+
+Readiness does **not** hide application deployment inside environment preparation.
+
+Application container/process deployment, release-specific migration, application route registration, live application health/readiness, live smoke validation, and release-specific deployment/rollback evidence belong to `/deploy` when the repository's deployment contract includes them.
+
+This distinction prevents a first-deploy deadlock: readiness proves that the environment can safely accept the selected artifact; `/deploy` creates and validates the live application state.
+
+## Pre-deploy versus post-deploy evidence
+
+Pre-deploy readiness may require:
+
+- verified machine/target binding and host identity;
+- actual target OS/architecture and supported runtime/platform;
+- validated/available route names and collision checks;
+- approved immutable artifact identity;
+- registry/artifact access readiness;
+- persistence/data/backup prerequisites;
+- migration capability;
+- deployment locking capability;
+- rollback/recovery capability and boundaries;
+- stronger Production backup/recovery prerequisites when applicable.
+
+Do not require first-deploy evidence that can only exist after the selected artifact is deployed, such as live route resolution, live application health, smoke success, deployed release identity, or execution-backed rollback evidence for that release.
+
+`/deploy` establishes those post-deploy facts and reports them from repository/tool evidence.
+
 ## Existing and new workstations
 
 On an already-configured workstation, successful strict verification means onboarding/setup questions are skipped.
@@ -81,13 +116,13 @@ Readiness is environment-specific. Readiness of Staging does not prove Productio
 
 Production remains a role with stronger deployment, artifact, backup, recovery, and Human-in-the-Loop policy where required. It does not use a separate readiness command.
 
-Once the selected environment is ready, the repeatable deployment entry point is:
+Once the selected environment is ready to deploy, the repeatable deployment entry point is:
 
 ```text
 /deploy <environment>
 ```
 
-`/deploy` verifies the selected environment/target/artifact evidence, dispatches to repository-provided tooling, and presents the applicable write gate immediately before execution.
+`/deploy` verifies the selected environment/target/artifact evidence, presents the applicable write gate immediately before execution, delegates deterministic deployment mechanics, and then verifies repository-defined live route/readiness/smoke/deployment evidence.
 
 A Production deployment remains separately authorized and never becomes implicit because readiness passed. A non-production remote deployment still requires the repository/tool's bounded remote-write authorization.
 

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

@@ -304,12 +304,14 @@ and preserve the branch.
 
 ## 12. Deployment handoff
 
-If the delivered work item owns release/deployment engineering, successful engineering delivery may hand off to:
+If the delivered work item owns release/deployment engineering, successful engineering delivery may hand off to the selected environment's state-driven readiness workflow:
 
 ```text
-/deployment-readiness <deployment-enabler-ID> enable [environment]
+/deployment-readiness <environment>
 ```
 
+Readiness re-discovers current state and continues from the furthest safe point; do not ask the human to choose `discovery`, `enable`, or `resume` merely because engineering delivery just completed.
+
 The readiness workflow is environment-generic. Production remains an environment role with stronger policy; merge approval never implies remote or production-deployment authorization.
 
 ## 13. Relationship to /start-work, /next-step, and /cleanup-branches

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 package/deployment provenance, selects the exact target/artifact, preserves tool-specific authorization, and delegates deterministic execution to repository-provided deployment tooling."
+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."
 argument-hint: "[environment] [release-or-artifact]"
 user-invocable: true
 disable-model-invocation: true
@@ -8,9 +8,9 @@ disable-model-invocation: true
 
 # Deploy
 
-`/deploy` is the normal human-facing deployment interface once deployment engineering and the selected environment are ready.
+`/deploy` is the normal human-facing deployment interface once deployment engineering is delivered and the selected environment is **ready to deploy**.
 
-Core owns interaction, validation, target safety, and Human-in-the-Loop authorization. Repository-provided deployment tooling owns deployment mechanics.
+Core owns interaction, validation, target safety, Human-in-the-Loop authorization, and evidence-oriented orchestration. Repository-provided deployment tooling owns deployment mechanics.
 
 Do not implement Docker, SSH, route, migration, or application deployment logic directly in this skill when an approved repository command exists.
 
@@ -24,7 +24,7 @@ Read only the minimum repository context needed to identify:
 - `DEPLOYMENT_BASELINE.json` when present;
 - approved deployment/release requirements;
 - configured named environments and checkout-local target bindings;
-- selected environment readiness evidence;
+- 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.
@@ -39,7 +39,9 @@ tools/lean-deployment/lean-poc-deploy.py
 
 over reconstructing Deployment Kit commands by hand or requiring a separate Kit checkout.
 
-If package/component baseline integrity is already known to be drifted, or deployment engineering/readiness is incomplete, stop and route to `/lean-update`, `/upstream-fix`, the deployment work item, or `/deployment-readiness` as appropriate.
+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.
+
+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 an environment explicitly
 
@@ -52,7 +54,7 @@ Rules:
 - 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`;
+- 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.
 
 ## 3. Resolve and verify the machine/target binding
@@ -105,7 +107,31 @@ For non-production, use only the broader artifact policy explicitly allowed by t
 
 When promoting a tested artifact to production, prefer the exact same immutable artifact/digest rather than rebuilding it.
 
-## 6. Preserve the deployment tool's exact authorization contract
+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.
+
+## 6. Build the deterministic deployment plan
+
+Use repository-provided tooling to construct or inspect the exact plan when supported.
+
+The plan may include, according to the repository contract:
+
+```text
+pre-deploy backup or safety check
+→ release-specific migration
+→ application/container deployment
+→ application route registration/update
+→ 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.
+
+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.
+
+## 7. Preserve the deployment tool's exact authorization contract
 
 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.
 
@@ -122,7 +148,7 @@ Authorization applies only to the exact environment, verified target, artifact,
 
 No requirements approval, code review, PR merge, CI pass, environment selection, prior deployment, or readiness result implicitly authorizes a deployment write.
 
-## 7. Present the deployment preview and gate
+## 8. Present the deployment preview and gate
 
 Before the modifying command show the resolved non-secret facts:
 
@@ -136,8 +162,10 @@ Target OS: <verified>
 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>
-Readiness blockers: NONE
+Post-deploy validation: route/health/smoke/evidence checks that will run after the write
 ```
 
 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.
@@ -152,7 +180,7 @@ For production require the project's explicit production deployment gate and the
 
 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.
 
-## 8. Execute only the approved script contract
+## 9. Execute only the approved script contract
 
 After authorization invoke only the repository-provided launcher with the explicitly selected environment and approved artifact inputs.
 
@@ -160,9 +188,22 @@ Do not perform unrelated host provisioning, target rebinding, firewall changes,
 
 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.
 
-## 9. Verify and record outcome
+If a failure occurs after a partial deployment, use only repository/tool-defined safe failure handling. Do not improvise destructive rollback or database recovery.
 
-After execution, use repository-provided readiness/smoke/evidence commands when available.
+## 10. Verify live deployment and record outcome
+
+After execution, use repository-provided inventory, route, readiness, health, smoke, and evidence commands when available.
+
+For a first deployment, this is where evidence such as the following becomes meaningful:
+
+- 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.
 
 Report only evidence-backed outcomes:
 
@@ -171,9 +212,26 @@ Report only evidence-backed outcomes:
 - deployment baseline/tool identity when relevant;
 - release/artifact identity;
 - deployment result;
-- readiness/smoke result;
-- rollback/recovery outcome when applicable.
+- route result when applicable;
+- readiness/health/smoke result;
+- migration result when applicable;
+- rollback/recovery capability/evidence when applicable.
 
 Do not report success merely because a command returned or a container/process started if stronger readiness evidence is required.
 
-Application rollback, database restore, destructive recovery, and environment tear-down remain separate decisions when the repository contract makes them separate.
+A successful deployment may be summarized as:
+
+```text
+DEPLOYMENT VALIDATED
+
+Environment: <name>
+Artifact: <exact immutable identity>
+Route: READY / NOT APPLICABLE
+Application health: READY
+Smoke: PASSED
+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.
+
+Application rollback execution, database restore/destructive recovery, and environment tear-down remain separate decisions when the repository contract makes them separate.

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

@@ -1,7 +1,7 @@
 ---
 name: deployment-readiness
-description: Guided readiness for any named deployment environment. Discovers and confirms simple machine facts first, verifies access/trust safely, repairs only missing setup, and hands ready environments to /deploy.
-argument-hint: "[deployment-enabler-ID] [status|discovery|enable|resume] [environment]"
+description: Guided readiness for any named deployment environment. Discovers current state, verifies access and pre-deploy prerequisites, repairs only missing setup, and hands environments that are ready to deploy to /deploy.
+argument-hint: "[environment] | status [environment]"
 user-invocable: true
 disable-model-invocation: true
 ---
@@ -10,17 +10,24 @@ disable-model-invocation: true
 
 `/deployment-readiness` is the reusable operational workflow for preparing named deployment environments such as Staging, Production, test, demo, or another repository-approved environment.
 
-It is not a deployment executor and it is not a production-only workflow. Production is an environment role/policy with stronger gates, not a separate readiness mechanism.
+It is not the application deployment executor and it is not production-only. Production is an environment role/policy with stronger gates, not a separate readiness mechanism.
 
-Modes:
+The normal human-facing invocation is:
 
 ```text
-status
-discovery
-enable
-resume
+/deployment-readiness <environment>
 ```
 
+The workflow is state-driven and resumable. It discovers whether the environment is unconfigured, partially configured, access-ready, platform-ready, or ready to deploy, then continues from the furthest safe observed state. Do not require the human to choose `discovery`, `enable`, or `resume` modes.
+
+For a read-only overview, support:
+
+```text
+/deployment-readiness status [environment]
+```
+
+For compatibility, if an older invocation includes a deployment-enabler ID and/or the legacy `discovery`, `enable`, or `resume` token, normalize it to the same state-driven workflow rather than forcing the human to restart. Do not advertise those legacy forms as the normal interface.
+
 ## 1. Resolve minimum context
 
 Read `.github/lean-workspace.json` when present plus only the relevant deployment enabler requirements/decisions/readiness record, release/deployment guidance, environment configuration contract, current package/deployment baselines, and repository-provided deployment tooling.
@@ -36,6 +43,8 @@ Do not assume:
 - SSH alias or discovery mechanism;
 - certificate model or hosting environment.
 
+If the invocation does not name an environment and more than one configured environment exists, ask the human to select one. Never silently default to Production.
+
 ## 2. Human-facing information model
 
 Keep the interaction centered on facts a person normally knows about the selected environment's machine:
@@ -56,6 +65,40 @@ Do not lead with questions such as `What is the logical target name?`. If an int
 
 Never use an application-specific example to imply that a reusable machine identity belongs to one POC. A machine/profile may legitimately be reused by multiple POCs while each POC keeps independent environment bindings, application state, data, routes, and deployment evidence.
 
+### Application route/address defaults
+
+Keep the machine's hostname/address separate from the application's route hostname. A target such as `server.local` may host many POCs, while each application owns its own route aliases.
+
+When the repository or installed deployment tooling defines a deterministic application-route convention from stable inputs such as `appSlug + environment`, derive and present that exact conventional set before asking for a free-form hostname. Treat the derived values as recommended defaults for confirmation, not as permission to register or change a route.
+
+For example, if the installed trusted-LAN deployment contract defines environment-scoped aliases such as:
+
+```text
+<app-slug>-<environment>.local
+<app-slug>.<environment>.local
+```
+
+present the concrete derived values in plain language:
+
+```text
+STAGING APPLICATION ADDRESS
+
+Recommended defaults:
+  <derived alias 1>
+  <derived alias 2>
+
+1. Use these defaults — recommended
+2. Choose different hostnames
+```
+
+Do not ask `What route hostname(s) should this environment use?` while a repository/tool-owned deterministic default is available and no collision or policy conflict has been observed.
+
+If the installed convention requires multiple compatibility aliases, preserve the complete default set. Do not silently drop one alias. If the convention defines an optional short alias with a larger collision surface, do not infer or add it; present it only when the repository/tool contract calls for an explicit opt-in.
+
+If the user rejects the defaults, or a read-only collision/policy check shows they cannot be used, ask for the smallest unresolved custom value and validate it through the installed tool's hostname contract.
+
+Selecting or confirming application route hostnames is configuration/readiness work only. It never authorizes DNS changes, route registration, Caddy changes, or another remote write; those retain their repository/tool-specific write gate.
+
 ## 3. Discover first, then ask only for missing facts
 
 Invocation begins read-only.
@@ -141,54 +184,45 @@ Then ask one material fact at a time, such as the SSH/deployment user, only when
 
 Once the human-facing machine facts are known, use repository/Deployment-Kit tooling to create the required internal profile/binding. Prefer deriving/reusing a stable internal identifier from confirmed state when the installed tooling supports it. Surface that identifier only when ambiguity or troubleshooting makes it useful.
 
-## 4. Mode boundaries
+## 4. State-driven progression
 
-### status
-
-Read-only overview.
-
-With an environment, summarize that environment's local configuration/readiness state.
-
-Without an environment, summarize all configured named deployment environments without remotely probing every machine:
+Normal readiness cadence is:
 
 ```text
-Environment   Role            Local setup     Last readiness
-Staging       non-production  CONFIGURED      READY / STALE / UNKNOWN
-Production    production      PARTIAL         NOT READY
+select environment
+→ rediscover current local state
+→ show/confirm known simple facts
+→ verify/reuse access
+→ repair only missing setup when authorized
+→ verify target OS/platform/security prerequisites
+→ verify artifact/registry/data/migration/rollback capability prerequisites
+→ ENVIRONMENT READY TO DEPLOY
+→ /deploy <environment>
 ```
 
-Use only evidence that actually exists. `status` does not authorize remote checks or writes.
-
-### discovery
+Each invocation resumes from observed evidence. Do not make the human rerun the command with a different mode merely because discovery completed or a prerequisite was repaired.
 
-May begin early after the application's foundation/walking skeleton is proven.
+Readiness may perform bounded environment-enablement writes when they are necessary and separately authorized, such as local profile/key/trust setup, target-side access setup, runtime/platform prerequisite setup, data/backup directory preparation, firewall preparation, or registry credential setup. These are readiness/setup operations, not application deployment.
 
-Purpose:
+Application deployment remains owned by `/deploy`.
 
-- identify intended named deployment environments and their roles;
-- discover/reuse existing workstation setup before asking questions;
-- confirm simple machine facts with the human;
-- discover each selected environment's real target and expected target OS;
-- identify access/security/network/TLS/certificate dependencies;
-- establish the environment-to-target readiness contract without embedding secrets in reusable source;
-- record non-secret facts in the repository-approved place;
-- surface blockers early.
+### Read-only status
 
-Discovery does not authorize remote writes or application deployment.
+`/deployment-readiness status [environment]` is a read-only overview.
 
-### enable
+With an environment, summarize that environment's local configuration/readiness state. Without an environment, summarize all configured named deployment environments without remotely probing every machine:
 
-Require evidence that deployment engineering completed the normal delivery path, including applicable requirements/review/merge/default-branch CI and repository-policy evidence.
-
-Enablement prepares the selected environment so `/deploy` can safely use it. It does not itself authorize application deployment.
-
-### resume
+```text
+Environment   Role            Local setup     Last readiness
+Staging       non-production  CONFIGURED      READY TO DEPLOY / STALE / UNKNOWN
+Production    production      PARTIAL         NOT READY
+```
 
-Continue from existing environment-specific readiness evidence. Re-discover current local state first and do not re-ask facts that remain valid.
+Use only evidence that actually exists. `status` does not authorize remote checks or writes.
 
 ## 5. Select the environment before environment-specific readiness
 
-When more than one configured deployment environment exists, select the environment being discovered or enabled before environment-specific questions or remote checks.
+When more than one configured deployment environment exists, select the environment before environment-specific questions or remote checks.
 
 Keep these concepts separate internally even when the human-facing interaction stays simple:
 
@@ -218,7 +252,7 @@ discover existing state
 → ask one missing material fact
 → record permitted non-secret fact
 → explain impact/blocker
-→ continue
+→ continue from the resulting state
 ```
 
 Use concise choices for bounded decisions. Ask factual values such as hostname/IP, username, port, OS/version, path, or observed system state as direct free-form/confirmation questions.
@@ -272,27 +306,39 @@ Possible missing state includes profile/binding, key, SSH-agent membership, inde
 
 Do not create duplicate credentials merely because another POC uses the same machine. Reuse an already-valid developer-to-machine relationship when the installed tooling and policy allow it.
 
-## 9. Network, security, DNS, TLS, runtime, and storage
+## 9. Pre-deploy readiness versus post-deploy validation
+
+Readiness answers: **can `/deploy` safely perform the selected environment's deployment now?**
 
-After basic machine/access facts are established, discover/verify only what the selected environment's approved role requires, such as:
+Before declaring the selected environment ready to deploy, verify only evidence that can exist before the deployment of the selected artifact, such as:
+
+- selected environment and confirmed machine/target binding;
+- strict connectivity/host-identity verification;
+- supported developer-workstation launcher;
+- expected target OS matches actual target OS;
+- shared runtime/platform prerequisites;
+- approved release/artifact policy;
+- immutable artifact/image digest when applicable;
+- artifact/registry accessibility or credential readiness;
+- route names validated and collision-free when the installed routing contract supports read-only inventory/plan checks;
+- independent environment data/backup paths or the approved ability to create/use them;
+- migration capability and prerequisites;
+- deployment lock capability;
+- rollback/recovery capability and required boundaries;
+- production-specific backup/recovery prerequisites when applicable;
+- unresolved security blockers = none.
 
-- actual target OS/version/architecture;
-- runtime/container support;
-- storage/data/backup paths;
-- inbound/outbound network dependencies;
-- firewall/security approvals;
-- DNS/server name;
-- HTTP/HTTPS and TLS/certificate model;
-- registry/artifact access;
-- migration/readiness/smoke/rollback/recovery prerequisites.
+Do **not** require evidence that can only be produced by deploying the exact selected artifact. On a first deployment, live application route resolution, application health/readiness, smoke results, deployed-release identity, and execution-backed rollback evidence are post-deploy validation, not pre-deploy blockers.
 
-Do not front-load these questions before basic environment/machine identity is understood.
+A previously deployed environment may have historical live evidence, but stale evidence for an older artifact does not prove the new artifact's post-deploy behavior.
+
+A non-production environment may use a less restrictive artifact policy only when approved requirements say so. Do not infer relaxed Staging behavior.
 
 ## 10. Bounded setup/provisioning writes
 
 A missing prerequisite is not authorization to change it.
 
-Examples of bounded actions include:
+Examples of bounded readiness actions include:
 
 ```text
 Create/update local environment binding [LOCAL CONFIG WRITE]
@@ -309,45 +355,30 @@ Set source-hosting environment variable/secret [SOURCE-HOSTING WRITE]
 
 Use the installed repository/tool's exact authorization phrase when it defines one. Do not weaken or replace that contract with a generic label.
 
-## 11. Environment deployment readiness
+Do not register the application route, deploy the application container/process, migrate the selected release, or run release-specific live smoke validation as a hidden readiness side effect. Those belong to `/deploy` when the repository deployment contract includes them.
 
-Before declaring the selected environment ready for `/deploy`, verify the evidence required by its approved role/policy.
+## 11. Readiness handoff
 
-Common evidence includes:
-
-- selected environment and confirmed machine/target binding;
-- strict connectivity/host-identity verification;
-- supported developer-workstation launcher;
-- expected target OS matches actual target OS;
-- approved release/artifact policy;
-- immutable artifact/image digest when applicable;
-- artifact/registry access;
-- independent environment data/backup paths;
-- migration path;
-- deployment lock behavior;
-- readiness and smoke checks;
-- application rollback;
-- explicit database-restore/recovery boundary;
-- unresolved security blockers = none.
-
-A non-production environment may use a less restrictive artifact policy only when approved requirements say so. Do not infer relaxed Staging behavior.
-
-## 12. Readiness handoff
-
-For any selected environment that is ready:
+For any selected environment that has satisfied its pre-deploy requirements:
 
 ```text
-ENVIRONMENT READY FOR DEPLOYMENT WORKFLOW
+ENVIRONMENT READY TO DEPLOY
 
 Environment: <name>
 Role: <role>
 Hostname/address: <confirmed non-secret value when appropriate>
 Target OS/architecture: <verified>
 Access/host identity: VERIFIED
-Release/artifact policy: <verified>
+Platform prerequisites: READY
+Route identity/plan: VALID / AVAILABLE when applicable
+Release/artifact: <verified immutable identity when required>
+Registry/artifact access: READY when applicable
+Persistence/migration capability: READY
+Rollback/recovery capability: READY
 Security blockers: NONE
-Readiness/Smoke: READY
-Rollback: READY
+
+POST-DEPLOY VALIDATION PENDING
+Live route/health/smoke/release-specific rollback evidence is established by /deploy.
 
 NEXT
 /deploy <environment>
@@ -355,15 +386,15 @@ NEXT
 
 For a production-role environment, include the additional production policy/backup/recovery evidence required by the project, but do not change the readiness mechanism or command name.
 
-This is readiness evidence, not deployment authorization. `/deploy` owns the actual deployment write gate for the exact environment, verified target, artifact, and current evidence.
+This is pre-deploy readiness evidence, not deployment authorization. `/deploy` owns the actual deployment write gate for the exact environment, verified target, artifact, and current evidence.
 
-## 13. Post-readiness
+## 12. Post-readiness
 
-Once an environment is ready:
+Once an environment is ready to deploy:
 
-- record non-secret readiness evidence in the repository-approved place;
+- record non-secret readiness evidence in the repository-approved place when useful;
 - keep readiness independent from other environments;
-- use `/deploy [environment]` for repeatable deployment;
-- return to `/deployment-readiness` when machine binding, address, expected OS/runtime, security posture, credentials, or another material prerequisite changes.
+- use `/deploy <environment>` for the application deployment and release-specific live validation;
+- return to `/deployment-readiness <environment>` when machine binding, address, expected OS/runtime, security posture, credentials, registry access, data prerequisites, or another material pre-deploy prerequisite changes.
 
-Application rollback, database restore/destructive recovery, and environment tear-down remain separately governed when data safety warrants it.
+Application rollback execution, database restore/destructive recovery, and environment tear-down remain separately governed when data safety warrants it.

package/assets/generated/core/core/skills/next-step/SKILL.md

@@ -60,7 +60,8 @@ MERGED_DEFAULT_BRANCH_CI_PENDING
 MERGED_DEFAULT_BRANCH_CI_FAILED
 DELIVERY_COMPLETE
 ENVIRONMENT_READINESS_PENDING
-ENVIRONMENT_READY
+ENVIRONMENT_READY_TO_DEPLOY
+DEPLOYMENT_VALIDATION_PENDING
 ```
 
 Use only states supported by observed evidence.
@@ -143,26 +144,28 @@ After merge:
 
 ## 6. Deployment handoff
 
-For a release/deployment engineering enabler after engineering delivery is complete, recommend:
+For release/deployment engineering after engineering delivery is complete, recommend the selected environment's state-driven readiness workflow:
 
 ```text
-/deployment-readiness <deployment-enabler-ID> enable [environment]
+/deployment-readiness <environment>
 ```
 
-when the selected environment still needs operational discovery/enablement.
+Use the same command whether the environment still needs initial discovery, prerequisite setup, repair, or final pre-deploy verification. Readiness re-discovers current state and resumes automatically; do not tell the human to choose `discovery`, `enable`, or `resume` modes.
 
-When evidence shows a configured named environment is ready for deployment, recommend:
+When evidence shows a configured named environment is ready to deploy, recommend:
 
 ```text
-/deploy [environment]
+/deploy <environment>
 ```
 
-rather than treating `/deployment-readiness` as the application-deployment executor.
+`ENVIRONMENT_READY_TO_DEPLOY` means pre-deploy prerequisites are satisfied. It does not require live application health, smoke, route resolution, or release-specific rollback evidence that can only be established by deploying the selected artifact.
+
+After `/deploy`, use repository/tool evidence to distinguish a successfully validated deployment from `DEPLOYMENT_VALIDATION_PENDING` or a deployment failure.
 
 When the user asks for readiness across configured environments, recommend the read-only overview:
 
 ```text
-/deployment-readiness <deployment-enabler-ID> status
+/deployment-readiness status
 ```
 
 Do not infer readiness of one environment from another. Production is never an implicit/default environment, and `/next-step` never authorizes a remote or production deployment merely by recommending `/deploy`.

package/assets/generated/core/core/skills/start-work/SKILL.md

@@ -159,20 +159,22 @@ For LIGHT work, branch setup is part of the human-selected implementation action
 
 When a work item owns release/deployment engineering or environment enablement, classify it ELEVATED when the change materially affects deployment/recovery/security behavior.
 
-Environment discovery may begin early with:
+Environment readiness may begin early with the normal state-driven interface:
 
 ```text
-/deployment-readiness <deployment-enabler-ID> discovery [environment]
+/deployment-readiness <environment>
 ```
 
-Discovery begins with existing local/repository configuration, shows simple known machine facts for confirmation, and does not authorize remote writes or deployment.
+It begins with existing local/repository configuration, shows simple known machine facts for confirmation, and continues only as far as current engineering/evidence safely allows. It does not authorize application deployment.
 
-After implementation review/local acceptance, use `/deliver`. After `/deliver` reports the merge, default-branch CI, and applicable repository-policy evidence satisfied, hand off to:
+After implementation review/local acceptance, use `/deliver`. After `/deliver` reports the merge, default-branch CI, and applicable repository-policy evidence satisfied, return to the same state-driven readiness command for the selected environment:
 
 ```text
-/deployment-readiness <deployment-enabler-ID> enable [environment]
+/deployment-readiness <environment>
 ```
 
+The workflow re-discovers state and continues from the furthest safe point; do not require the human to switch from a discovery mode to an enable mode.
+
 Production remains a role with stronger policy and deployment authorization; it does not use a separate readiness workflow.
 
 ## 8. Guided ending

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mriekki/lean",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Public consumer distribution and updater for Lean engineering assets.",
   "type": "module",
   "bin": {

package/src/cli.mjs

@@ -11,7 +11,8 @@ function parseArgs(argv) {
   const positional = [];
   for (let i = 0; i < argv.length; i += 1) {
     const arg = argv[i];
-    if (arg === '--apply' || arg === '--yes') options.apply = true;
+    if (arg === '--help' || arg === '-h') options.help = true;
+    else if (arg === '--apply' || arg === '--yes') options.apply = true;
     else if (arg === '--root') options.root = argv[++i];
     else if (arg === '--profile') options.profile = argv[++i];
     else if (arg === '--consumer') options.consumer = argv[++i];
@@ -65,13 +66,31 @@ async function shouldApply(options) {
   }
 }
 
-function usage() {
-  console.log(`@mriekki/lean\n\nCommands:\n  install   Preview/install bundled Lean assets\n  update    Preview/update to this package's bundled Lean assets\n  status    Show installed umbrella/component provenance\n  check     Verify managed files and baselines exactly match this package\n  version   Show package version\n\nCommon options:\n  --root PATH\n  --profile greenfield-poc\n  --apply | --yes\n  --consumer NAME\n  --consumer-baseline LABEL\n  --accept-retired core:path\n`);
+function usage(command) {
+  const commandUsage = {
+    install: 'lean install [--root PATH] [--profile NAME] [--apply|--yes] [--consumer NAME] [--consumer-baseline LABEL] [--accept-retired component:path]',
+    update: 'lean update [--root PATH] [--profile NAME] [--apply|--yes] [--accept-retired component:path]',
+    status: 'lean status [--root PATH] [--profile NAME]',
+    check: 'lean check [--root PATH] [--profile NAME]',
+    version: 'lean version'
+  };
+
+  if (commandUsage[command]) {
+    console.log(`@mriekki/lean\n\nUsage:\n  ${commandUsage[command]}\n`);
+    return;
+  }
+
+  console.log(`@mriekki/lean\n\nCommands:\n  install   Preview/install bundled Lean assets\n  update    Preview/update to this package's bundled Lean assets\n  status    Show installed umbrella/component provenance\n  check     Verify managed files and baselines exactly match this package\n  version   Show package version\n\nCommon options:\n  --root PATH\n  --profile greenfield-poc\n  --apply | --yes\n  --consumer NAME\n  --consumer-baseline LABEL\n  --accept-retired core:path\n  -h, --help\n`);
 }
 
 export async function run(argv = process.argv.slice(2), packageData = loadPackageData()) {
   const { command, options } = parseArgs(argv);
-  if (command === 'help' || command === '--help') { usage(); return 0; }
+  if (command === 'help') { usage(); return 0; }
+  if (options.help) {
+    if (!['install', 'update', 'status', 'check', 'version'].includes(command)) throw new Error(`Unknown command: ${command}`);
+    usage(command);
+    return 0;
+  }
   if (command === 'version') { console.log(`${packageData.pkg.name} ${packageData.pkg.version}`); return 0; }
   const root = path.resolve(options.root ?? process.cwd());
   if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) throw new Error(`Repository root not found: ${root}`);