@mriekki/lean 0.1.0 → 0.2.0

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

@@ -1,6 +1,6 @@
 ---
 name: deploy
-description: "Guided deployment orchestration for a configured named environment. Selects and verifies the environment/target, preserves production gates, and delegates deterministic execution to repository-provided platform scripts."
+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."
 argument-hint: "[environment] [release-or-artifact]"
 user-invocable: true
 disable-model-invocation: true
@@ -10,59 +10,50 @@ disable-model-invocation: true
 
 `/deploy` is the normal human-facing deployment interface once deployment engineering and the selected environment are ready.
 
-The skill owns interaction, validation, target safety, and authorization. Repository-provided scripts own deployment mechanics.
+Core owns interaction, validation, target safety, and Human-in-the-Loop authorization. Repository-provided deployment tooling owns deployment mechanics.
 
-Do not implement application deployment logic directly in the skill when an approved repository script exists.
+Do not implement Docker, SSH, route, migration, or application deployment logic directly in this skill when an approved repository command exists.
 
-## 1. Begin read-only
+## 1. Begin read-only and establish provenance
 
 Invocation starts read-only.
 
 Read only the minimum repository context needed to identify:
 
-- the approved deployment/release requirements,
-- configured named deployment environments,
-- checkout-local environment-to-target bindings when the project uses them,
-- the selected environment's readiness evidence,
-- the approved release/artifact policy,
-- repository-provided deployment entry points,
+- `LEAN_BASELINE.json` when the repository is package-managed;
+- `DEPLOYMENT_BASELINE.json` when present;
+- approved deployment/release requirements;
+- configured named environments and checkout-local target bindings;
+- selected environment 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 file names, script paths, target OS, SSH aliases, container runtime, or release format unless the repository establishes them.
+Do not assume configuration filenames, target OS, SSH aliases, container runtime, or release format unless the repository establishes them.
 
-If deployment engineering is not delivered or the selected environment is not operationally ready, stop and route to the repository's deployment work item or `/production-readiness` as appropriate.
-
-## 2. Select an environment explicitly
-
-If the invocation did not name an environment, enumerate only environments configured for this checkout and ask the human to select one.
-
-Show enough non-secret identity to distinguish them, for example:
+When `DEPLOYMENT_BASELINE.json` identifies the standard Lean POC Deployment Kit and its generated entry point exists, prefer the repository-distributed interface such as:
 
 ```text
-SELECT DEPLOYMENT ENVIRONMENT
+tools/lean-deployment/lean-poc-deploy.py
+```
 
-1. staging
-   Role: non-production
-   Target: portable-ubuntu
-   [REMOTE WRITE]
+over reconstructing Deployment Kit commands by hand or requiring a separate Kit checkout.
 
-2. production
-   Role: production
-   Target: home-production
-   [PRODUCTION WRITE]
+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 `/production-readiness` as appropriate.
 
-3. Stop
-```
+## 2. Select an environment explicitly
 
-Environment names and target labels above are examples only.
+If the invocation did not name an environment, enumerate only environments configured for this checkout and ask the human to select one.
+
+Show enough non-secret identity to distinguish them.
 
 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 an environment is named but is not configured in this checkout, fail explicitly;
-- selecting an environment chooses scope but does not itself authorize the deployment write.
+- if a named environment is not configured, fail explicitly;
+- selecting an environment chooses scope but does not authorize the deployment write.
 
 ## 3. Resolve and verify the target binding
 
@@ -78,66 +69,61 @@ named environment
 
 Address discovery is not host trust.
 
-Before a remote deployment:
+Before remote deployment:
 
 - verify the selected environment resolves to its configured target;
-- use the repository-approved stable target/SSH alias rather than a hard-coded transient address when that is the approved design;
-- preserve enrolled SSH host-key verification independently of the current IP address;
-- stop on an unknown host identity or changed host key;
+- use the repository-approved stable logical target rather than a guessed transient address;
+- preserve enrolled host-key verification independently of current IP;
+- 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 the actual target OS is compatible with the environment's approved expected target OS before choosing target-specific deployment behavior.
+- verify actual target OS compatibility before target-specific behavior.
 
-Changing an environment's bound target is configuration/readiness work, not a deployment fallback. Stop and route to the approved rebind/readiness workflow when rebinding is needed.
+Changing an environment's target is readiness/configuration work, not deployment fallback.
 
 Keep private keys, passphrases, credentials, copied trust databases, and other secret values out of repository configuration and logs.
 
-## 4. Select the local launcher by developer workstation OS
+## 4. Resolve the repository-provided launcher
 
-Use repository-provided platform-appropriate deployment entry points.
+Prefer the canonical repository-provided deployment interface established by the current deployment baseline.
 
-Typical dispatch is:
+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.
 
-```text
-Windows developer workstation → approved PowerShell deployment entry point
-macOS/Linux developer workstation → approved shell deployment entry point
-```
+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.
 
-The repository may define different supported launchers. Follow its contract rather than inventing a path.
+Launcher choice may depend on developer workstation OS; target behavior depends on selected target OS. Do not confuse those dimensions.
 
-The launcher choice is based on the developer workstation OS. Target-specific behavior is based on the selected environment's approved target OS. Do not confuse those two dimensions.
+If the approved launcher is absent, locally drifted, or unsupported on the current workstation/target, stop rather than inventing deployment mechanics.
 
-If the developer workstation or target OS is unsupported by the repository's approved deployment implementation, stop with a clear blocker.
+## 5. Resolve release/artifact identity
 
-## 5. Preserve one deployment contract across launchers
+Use the repository's approved policy for the selected environment.
 
-Where a repository provides multiple local launchers, they must preserve equivalent deployment semantics and safety behavior.
+For production require the approved formal release/artifact evidence, including immutable identity when required.
 
-Prefer a common logical contract such as:
+For non-production, use only the broader artifact policy explicitly allowed by the repository. Do not invent relaxed staging semantics.
 
-```text
-environment
-release/version or artifact identity
-immutable digest when required
-dry-run/check mode when supported
-```
+When promoting a tested artifact to production, prefer the exact same immutable artifact/digest rather than rebuilding it.
 
-Do not pass secret values on command lines merely to make launchers symmetric. Use the repository's approved protected credential mechanism.
+## 6. Preserve the deployment tool's exact authorization contract
 
-Environment-specific values are configuration, not reasons to duplicate otherwise equivalent deployment procedures.
+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.
 
-## 6. Resolve release/artifact identity
+For example, the standard Deployment Kit may require operation-specific phrases such as:
 
-Use the repository's approved policy for the selected environment.
+```text
+[APP DEPLOY WRITE]
+[PRODUCTION APP DEPLOY]
+```
 
-For a production-role environment, require the approved formal release/artifact evidence, including immutable identity when the project requires it.
+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.
 
-For non-production environments, the repository may allow the same formal release policy or a broader immutable CI/commit artifact policy. Do not invent broader permissions when the project has not approved them.
+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.
 
-When promoting a tested artifact from a non-production environment to production, prefer deploying the exact same immutable artifact/digest rather than rebuilding it for production.
+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 authorization gate
+## 7. Present the deployment preview and gate
 
-Before running the modifying deployment script, show the resolved non-secret facts:
+Before the modifying command show the resolved non-secret facts:
 
 ```text
 DEPLOYMENT READY
@@ -146,48 +132,45 @@ Environment: <name>
 Role: <production|non-production>
 Target: <verified logical target>
 Target OS: <verified>
-Launcher: <repository-provided script>
-Release/artifact: <verified identity>
+Launcher: <repository-provided command>
+Deployment baseline: <exact commit/distribution when present>
+Release/artifact: <verified immutable identity>
+Required authorization: <exact tool phrase or repository gate>
 Readiness blockers: NONE
 ```
 
-For a non-production remote deployment ask for one bounded authorization such as:
+For a non-production deployment ask for one bounded authorization covering the exact reviewed plan and required tool phrase.
 
-```text
-Authorize deployment to <environment>? [REMOTE WRITE]
-```
-
-For a production-role environment require the project's explicit production deployment gate:
+For production require the project's explicit production deployment gate and the exact installed tool phrase. Keep the consequence visible as:
 
 ```text
-Authorize deployment to <environment>? [PRODUCTION WRITE]
+[PRODUCTION WRITE]
 ```
 
-Production authorization applies only to the exact environment, verified target, release/artifact, and evidence shown. If any of those materially changes, stop and require renewed review/authorization.
-
-No requirements approval, code review, PR merge, CI pass, environment selection, prior deployment, or readiness result implicitly authorizes this deployment.
+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
 
-After authorization, invoke the repository-provided launcher with the explicitly selected environment and approved release/artifact inputs.
+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, or other out-of-band remote writes as part of `/deploy` unless they are explicitly part of the already-approved deployment script contract and authorization scope.
+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, or another blocker, stop according to the repository's deployment contract. Never redirect the deployment to another environment or host.
+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
 
-After the script completes, use repository-provided readiness/smoke checks and evidence recording when available.
+After execution, use repository-provided readiness/smoke/evidence commands when available.
 
-Report at least the non-secret outcome supported by evidence:
+Report only evidence-backed outcomes:
 
-- selected environment,
-- verified target identity/label,
-- release/artifact identity,
-- deployment result,
-- readiness/smoke result,
-- rollback outcome when applicable.
+- selected environment;
+- verified target identity/label;
+- deployment baseline/tool identity when relevant;
+- release/artifact identity;
+- deployment result;
+- readiness/smoke result;
+- rollback/recovery outcome when applicable.
 
-Do not report success merely because a command returned or a container/process started if the repository requires stronger readiness evidence.
+Do not report success merely because a command returned or a container/process started if stronger readiness evidence is required.
 
-Application rollback and database restore/destructive recovery remain separate decisions when the project contract makes them separate.
+Application rollback, database restore, destructive recovery, and environment tear-down remain separate decisions when the repository contract makes them separate.

package/assets/generated/core/core/skills/lean-update/SKILL.md

@@ -0,0 +1,189 @@
+---
+name: lean-update
+description: Guided whole-profile update for package-managed Lean consumers using the exact published @mriekki/lean artifact while preserving Core, Deployment, and umbrella baseline integrity.
+argument-hint: "[optional exact package version]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Lean Update
+
+`/lean-update` is the normal update workflow for consumers that contain `LEAN_BASELINE.json` and were installed/generated from the public Lean package.
+
+The governing rule is:
+
+```text
+package-managed consumer
+→ update the whole Lean profile through the published package
+→ keep LEAN_BASELINE.json + component baselines coherent
+```
+
+Do not replace this with direct Core-only or Deployment-Kit-only synchronization when `LEAN_BASELINE.json` is present.
+
+Invocation starts read-only. One explicit update choice may authorize safe branch setup plus the exact package apply and verification. `/deliver`, merge, release publication, and production deployment remain separate.
+
+## 1. Establish package-managed provenance
+
+From the consumer root read:
+
+- `LEAN_BASELINE.json`;
+- `CORE_BASELINE.json` when present;
+- `DEPLOYMENT_BASELINE.json` when present;
+- current Git status, branch, remotes, and default branch when observable.
+
+Require `LEAN_BASELINE.json` to identify:
+
+- package name;
+- installed package version;
+- profile;
+- recorded Core component commit/version/distribution;
+- recorded Deployment component commit/distribution when that component is present.
+
+If `LEAN_BASELINE.json` is absent, report `NOT A PACKAGE-MANAGED LEAN CONSUMER` and stop. A Core-only consumer may use `/core-sync`; another component-only consumer must use that component's canonical compatibility path.
+
+Do not synthesize or repair missing umbrella provenance by hand.
+
+## 2. Verify the installed package baseline first
+
+Before planning an update, verify that the current managed state still matches the exact installed package version recorded in `LEAN_BASELINE.json`.
+
+For the standard package this is equivalent to:
+
+```text
+npx --yes @mriekki/lean@<installed-version> check
+```
+
+Use the package identity recorded by the baseline rather than silently substituting another package.
+
+If the exact installed package cannot be obtained, or `check` reports stale/drifted Core, Deployment, or umbrella metadata, stop. Do not use an update as a way to overwrite unexplained managed drift.
+
+Also inspect Git state. Preserve unrelated consumer work; never auto-stash, reset, clean, rebase, force-update, or discard it.
+
+## 3. Resolve one exact target package
+
+If the human supplied an exact version, use that exact version after confirming it exists.
+
+Otherwise resolve the registry's current published version first, then pin that exact value for the remainder of the operation. For the standard package, typical read-only evidence is:
+
+```text
+npm view @mriekki/lean@latest version --json
+npm view @mriekki/lean@<resolved-version> dist.integrity --json
+```
+
+Do not use a moving `@latest` reference for the modifying apply after preview. Use the same exact package version for preview, apply, and final check.
+
+If the resolved version equals the installed version and the exact-version check passes, report `LEAN ALREADY CURRENT` and stop without creating a branch or commit.
+
+If the resolved target is semantically older than the installed package, report `LEAN DOWNGRADE REQUESTED` and stop. Normal `/lean-update` does not authorize a downgrade or rollback; that requires a separate explicit recovery/rollback decision with repository-specific evidence.
+
+## 4. Preview the whole-profile update
+
+Run the target package's update command without `--apply` and inspect the complete plan. For the standard package:
+
+```text
+npx --yes @mriekki/lean@<target-version> update
+```
+
+Do not approve the package's interactive apply prompt during preview. When needed, invoke preview in the environment's non-interactive/read-only form so the printed plan is observed without applying it.
+
+The preview must cover every component in the installed profile together. A managed conflict/drift in any component blocks the whole update.
+
+Stop on unsafe states such as:
+
+- `LOCAL_DRIFT`;
+- `CONFLICT`;
+- `LOCAL_MISSING`;
+- `UNTRACKED_CONFLICT`;
+- path collisions/conflicts;
+- unaccepted Core `RETIRED_PATH`.
+
+Core retired paths are an ownership-transfer decision. Never auto-add `--accept-retired core:<path>` merely to make the update pass. Explain the retired path and require a separate explicit ownership decision before re-previewing it.
+
+## 5. Present one bounded update choice
+
+When the exact target package plan is safe, present:
+
+```text
+LEAN UPDATE READY
+
+Installed: <package>@<installed-version>
+Target: <package>@<target-version>
+Profile: <profile>
+Core: <old> → <new>
+Deployment: <old> → <new> / unchanged
+Managed drift/conflicts: NONE
+
+1. Apply the exact Lean package update [GIT + FILE WRITE] — recommended
+2. Keep inspecting only [READ ONLY]
+3. Stop [NO ACTION]
+```
+
+Choosing option 1 authorizes only:
+
+- creation/switch to one repository-appropriate short-lived update branch when needed;
+- exact target package apply;
+- package/baseline verification;
+- inspection of the resulting meaningful diff.
+
+It does not authorize `/deliver`, merge, npm/Core/Deployment release publication, or deployment.
+
+## 6. Apply only the exact previewed package
+
+If the consumer is on its default branch, create/switch to a short-lived branch such as:
+
+```text
+chore/update-lean-<target-version>
+```
+
+Branch setup is routine inside the selected bounded update action when safe and unambiguous.
+
+Apply using the same exact package version that was previewed, for example:
+
+```text
+npx --yes @mriekki/lean@<target-version> update --apply
+```
+
+If explicit Core retired-path ownership transfer was separately approved, pass only the exact reviewed paths using the package's `--accept-retired core:<path>` contract. Never widen that set implicitly.
+
+Do not run direct `tools/package/sync.py`, Deployment Kit sync, or a remote `[sync-core]` request as part of a package-managed update.
+
+## 7. Verify all baselines and the diff
+
+After apply, run the exact target package check:
+
+```text
+npx --yes @mriekki/lean@<target-version> check
+```
+
+Then inspect:
+
+```text
+git status --short --branch
+git diff --stat
+git diff -- LEAN_BASELINE.json CORE_BASELINE.json DEPLOYMENT_BASELINE.json
+```
+
+Confirm:
+
+- `LEAN_BASELINE.json` records the exact target package/version/profile;
+- component baseline commits/distributions match the umbrella baseline;
+- package check passes for the whole profile;
+- consumer-owned content was not overwritten;
+- only intended package-managed changes and reviewed ownership transfers occurred.
+
+Present the meaningful diff for human review. After acceptance, recommend `/deliver` for normal commit/push/PR/CI mechanics.
+
+## 8. Boundaries
+
+`/lean-update` never:
+
+- updates only Core or only Deployment when `LEAN_BASELINE.json` manages them together;
+- uses a different package version for apply than the reviewed preview;
+- performs a downgrade/rollback as an ordinary update;
+- overwrites unexplained managed drift;
+- auto-accepts Core retired-path ownership transfer;
+- publishes npm/Core/Deployment releases or tags;
+- merges the consumer PR;
+- deploys an environment.
+
+If reusable shared content is wrong rather than merely outdated, route the defect through `/upstream-fix` first. Package-managed adoption of the accepted fix happens only after an accepted Lean package release contains that upstream commit.