@mriekki/lean 0.1.0 → 0.2.0

package/assets/generated/core/core/skills/upstream-fix/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: upstream-fix
-description: Route reusable bugs discovered in a consumer to the canonical shared repository, allow bounded upstream implementation, and return adoption to exact baseline sync.
+description: Route reusable bugs discovered in a consumer to the canonical shared repository, allow bounded upstream implementation, and return adoption through the consumer's actual provenance/update boundary.
 argument-hint: "[optional problem summary]"
 user-invocable: true
 disable-model-invocation: true
@@ -13,32 +13,26 @@ disable-model-invocation: true
 The governing rule is:
 
 ```text
-discover in the consumer
-→ diagnose/prove in the consumer
-→ fix in the owning canonical repository
+discover in consumer
+→ diagnose/prove in consumer
+→ fix in owning canonical repository
 → deliver there
-→ sync the accepted shared commit back into the consumer
-→ verify again in the consumer
+→ adopt through the consumer's recorded distribution boundary
+→ verify again in consumer
 ```
 
-A temporary edit to a shared-managed file inside the consumer may be useful as diagnosis/proof, but it is never the canonical delivered fix.
+A temporary edit to a shared-managed file inside a consumer may be useful as diagnosis/proof, but it is never the canonical delivered fix.
 
 ## 1. Invocation authorization
 
 Invoking `/upstream-fix` authorizes:
 
 - read-only ownership/provenance inspection in the consumer;
-- classification of the problem to the owning layer;
+- classification to the smallest canonical owner;
 - inspection of already-available local canonical repository candidates;
-- when ownership and the intended patch are clear and a canonical checkout is safe, routine creation/use of one short-lived canonical work branch and application of only the bounded equivalent fix plus its focused tests/docs.
+- when ownership and the bounded patch are clear and a canonical checkout is safe, routine creation/use of one short-lived canonical work branch and application of only that bounded fix plus focused tests/docs.
 
-Invocation does **not** authorize:
-
-- commit, push, PR creation, merge, release publication, or deployment;
-- rewriting/discarding consumer work;
-- changing more than one canonical repository in the same bounded fix;
-- broad filesystem scans or cloning shared repositories merely to satisfy the helper;
-- treating a temporary consumer patch as accepted shared implementation.
+Invocation does **not** authorize commit, push, PR creation, merge, release publication, package publication, deployment, rewriting/discarding consumer work, or changing multiple canonical repositories in one bounded fix.
 
 Normal review and `/deliver` occur later while focused on the owning canonical repository.
 
@@ -46,20 +40,16 @@ Normal review and `/deliver` occur later while focused on the owning canonical r
 
 From the consumer root inspect, when present:
 
+- `LEAN_BASELINE.json`;
 - `CORE_BASELINE.json`;
 - `DEPLOYMENT_BASELINE.json`;
 - `.github/lean-workspace.json`;
 - current Git branch/status/diff;
 - the files involved in the reported problem or temporary proof.
 
-Run repository-local managed-baseline checks when available:
-
-```text
-python tools/lean-core/check-core-baseline.py --root .
-python tools/lean-deployment/check-deployment-baseline.py
-```
+Run repository-local managed-baseline checks when available.
 
-Do not assume every generated-looking file is shared-owned. Use baseline managed-path records as the primary ownership evidence.
+Do not assume every generated-looking file is shared-owned. Use baseline managed-path records as the primary ownership evidence, and use `LEAN_BASELINE.json` to determine whether component baselines are managed together by an umbrella package.
 
 ## 3. Classify the owner
 
@@ -67,7 +57,7 @@ Use the smallest owning layer that would need the same fix for another consumer.
 
 ### Consumer-owned
 
-Examples: application domain logic, UI behavior, app-specific configuration, product tests, consumer architecture.
+Application domain logic, UI behavior, app-specific configuration, product tests, and consumer architecture normally remain consumer-owned.
 
 Result:
 
@@ -76,13 +66,11 @@ CONSUMER FIX
 Owner: current repository
 ```
 
-Stop upstream routing and continue through the consumer's normal `/start-work` / implementation / review / `/deliver` flow.
+Return to the consumer's normal `/start-work` / implementation / review / `/deliver` flow.
 
 ### Core-owned
 
-Evidence includes a changed/problematic path managed by `CORE_BASELINE.json`, or behavior defined by canonical Lean workflow skills/agents/instructions.
-
-Result:
+Evidence includes a path managed by `CORE_BASELINE.json` or behavior defined by reusable Core workflow assets.
 
 ```text
 CORE BUG
@@ -91,26 +79,33 @@ Owner: <repository recorded by CORE_BASELINE.json>
 
 ### Deployment-Kit-owned
 
-Evidence includes a changed/problematic path managed by `DEPLOYMENT_BASELINE.json`, or reusable deployment behavior owned by the pinned Deployment Kit.
-
-Result:
+Evidence includes a path managed by `DEPLOYMENT_BASELINE.json` or reusable deployment mechanics owned by that recorded Kit.
 
 ```text
 DEPLOYMENT BUG
 Owner: <repository recorded by DEPLOYMENT_BASELINE.json>
 ```
 
+### Package assembly / Lean Platform-owned
+
+When canonical component source is correct but the published package bytes, component pins, package engine, or umbrella baseline behavior is wrong:
+
+```text
+LEAN PLATFORM BUG
+Owner: package/platform repository supported by evidence
+```
+
 ### Generator/control-plane owned
 
-If generated output is wrong but the managed payload itself is correct, classify the generator/orchestrator rather than patching the generated consumer. Resolve ownership from repository/project evidence; do not guess between Bootstrap and a control plane when evidence is insufficient.
+If the package payload is correct but generation/publication/orchestration materializes it incorrectly, classify Bootstrap/control-plane ownership from evidence rather than patching a generated consumer.
 
-If ownership is genuinely ambiguous, stop at `UPSTREAM OWNER UNCLEAR` and present the competing evidence. Do not write to multiple repositories speculatively.
+If ownership is genuinely ambiguous, stop at `UPSTREAM OWNER UNCLEAR`. Do not write to multiple repositories speculatively.
 
 ## 4. Temporary consumer proof
 
-A temporary consumer edit to a shared-managed path is allowed for diagnosis when it helps prove the fix in the real application context.
+A temporary consumer edit to a shared-managed path is allowed for diagnosis when it proves the fix in real application context.
 
-Clearly report it as:
+Report it explicitly:
 
 ```text
 TEMPORARY SHARED-MANAGED PROOF
@@ -119,48 +114,38 @@ Canonical owner: <repo>
 Do not deliver this consumer copy.
 ```
 
-Do not silently revert/discard the proof, because it may contain useful evidence. Do not stage/commit it as ordinary consumer implementation. Adoption later replaces the private proof with the accepted shared baseline.
+Do not silently discard the proof and do not stage/commit it as ordinary consumer implementation.
 
-## 5. Resolve a canonical local checkout
+## 5. Resolve a safe canonical checkout
 
-For the classified owner, consider local candidates in this order:
+For the classified owner consider, in order:
 
-1. explicit path supplied by the human;
-2. an already-open workspace folder whose Git remote unambiguously matches the recorded canonical repository;
+1. an explicit path supplied by the human;
+2. an already-open workspace folder with the expected Git remote;
 3. a normal sibling checkout derived from the canonical repository name.
 
-Do not broadly scan the filesystem. A multi-root maintainer workspace is a convenience, not a requirement.
-
-A candidate is safe for bounded upstream implementation only when:
+Do not broadly scan the filesystem and do not clone automatically merely to continue.
 
-- it is the expected Git repository;
-- Git state can be inspected;
-- no merge/rebase/cherry-pick is in progress;
-- unrelated local work is absent;
-- branch state does not require reset/rebase/force/stash/discard operations.
-
-If no safe local canonical checkout exists, report the exact canonical repository and the proven consumer evidence. Do not clone automatically just to continue.
+A candidate is safe only when it is the expected repository, has no merge/rebase/cherry-pick in progress, has no unrelated local work, and does not require stash/reset/rebase/force/discard operations.
 
 ## 6. Port the bounded fix upstream
 
-When the safe local canonical checkout exists and the equivalent fix is clear:
-
-1. inspect the canonical implementation and tests before editing;
-2. create/use a repository-appropriate short-lived branch tied to the upstream issue/work item when needed;
-3. reproduce the root cause against canonical code where practical;
-4. apply the reusable fix in the canonical source, not by copying consumer-specific names/configuration;
-5. add/update focused canonical tests that would have caught the defect;
-6. update canonical docs only when the contract changed;
-7. run relevant local checks when available;
-8. show the canonical meaningful diff and observed validation.
+When a safe canonical checkout exists and the equivalent reusable fix is clear:
 
-Preserve consumer specificity. A shared fix must not hard-code the consumer name, target, data, environment, route, or product requirement merely because that consumer exposed the bug.
+1. inspect canonical implementation/tests before editing;
+2. create/use one repository-appropriate short-lived branch;
+3. reproduce the root cause canonically where practical;
+4. apply the reusable fix without consumer-specific names/configuration;
+5. add/update focused tests that would have caught the defect;
+6. update canonical docs when the contract changed;
+7. run relevant local checks;
+8. show the meaningful canonical diff and observed validation.
 
-If the consumer proof cannot be generalized safely, stop and reclassify or ask for a narrower canonical design rather than forcing the patch upstream.
+If the consumer proof cannot be generalized safely, stop and reclassify rather than forcing it upstream.
 
 ## 7. Handoff to canonical delivery
 
-After the upstream implementation is ready, report:
+When the upstream implementation is ready:
 
 ```text
 UPSTREAM FIX READY
@@ -172,23 +157,53 @@ Validation: <observed checks>
 Next: focus the canonical repository and run /deliver
 ```
 
-`/upstream-fix` does not commit/push/open/merge the canonical PR itself. `/deliver` retains the normal reviewed-diff and merge/finalize gates in exactly one repository.
+`/upstream-fix` does not commit/push/open/merge the canonical PR itself.
+
+## 8. Adopt the accepted fix through the right boundary
+
+After the canonical PR is merged and required default-branch CI is green, re-read the consumer provenance before choosing adoption.
+
+### Package-managed consumer (`LEAN_BASELINE.json` present)
+
+Do **not** direct-sync Core or Deployment Kit into the consumer.
+
+The accepted component fix must first become part of an accepted published Lean package:
+
+```text
+canonical Core/Deployment fix merged
+→ Lean Platform pins the exact accepted component commit
+→ Lean Platform PR + CI
+→ explicit package publication gate
+→ published exact @mriekki/lean version
+→ consumer /lean-update <version>
+```
+
+Until that package exists, report:
+
+```text
+PACKAGE RELEASE REQUIRED
+Consumer adoption is blocked on a Lean package that contains the accepted upstream commit.
+```
+
+Do not silently patch `LEAN_BASELINE.json`, `CORE_BASELINE.json`, or `DEPLOYMENT_BASELINE.json` to pretend the package contains the new component.
+
+### Component-only Core consumer (`LEAN_BASELINE.json` absent)
+
+A Core-owned fix may return through `/core-sync` using the exact accepted Core commit/distribution.
 
-## 8. Adopt the accepted fix back into the consumer
+### Component-only Deployment consumer (`LEAN_BASELINE.json` absent)
 
-After the canonical PR is merged and its accepted default-branch CI is green:
+A Deployment-owned fix may return through the canonical Deployment Kit compatibility sync and refresh `DEPLOYMENT_BASELINE.json`.
 
-- Core-owned fixes return through `/core-sync` using the exact accepted Core commit/distribution;
-- Deployment-Kit-owned fixes return through the canonical Deployment Kit consumer-sync capability and refresh `DEPLOYMENT_BASELINE.json`;
-- generator/control-plane fixes are validated by regenerating or using that platform's canonical update path, not by manually editing generated managed files.
+### Generator/control-plane fix
 
-Then rerun the original consumer reproduction and baseline checks.
+Validate through that platform's canonical regeneration/update path, never by manually editing generated managed files.
 
-A successful consumer retest is evidence that the shared fix works in context; it does not turn the consumer copy into the canonical source.
+Then rerun the original reproduction and baseline checks in the consumer.
 
 ## 9. Consumer delivery guard
 
-If `/deliver` is invoked in a consumer with unexplained Core- or Deployment-Kit-managed file drift, stop before staging/commit/push. Route reusable managed-file changes through `/upstream-fix` and accepted baseline sync first.
+If `/deliver` is invoked in a consumer with unexplained Core-, Deployment-, or Lean-package-managed drift, stop before staging/commit/push. Route reusable managed-file changes through `/upstream-fix` and then through the appropriate accepted update boundary.
 
 Consumer-owned changes may be delivered normally when managed baselines are clean.
 
@@ -197,10 +212,10 @@ Consumer-owned changes may be delivered normally when managed baselines are clea
 `/upstream-fix` never:
 
 - merges changes;
-- publishes releases/tags;
+- publishes releases/tags/packages;
 - deploys production;
-- commits one change across multiple repositories;
+- commits one bounded fix across multiple repositories;
 - auto-stashes, resets, rebases, force-pushes, or discards work;
-- turns a maintainer multi-root workspace into generated repository content;
 - requires ordinary consumer users to clone shared repositories;
-- treats a temporary shared-managed consumer edit as a legitimate permanent fork.
+- treats a temporary managed consumer edit as a permanent fork;
+- bypasses `LEAN_BASELINE.json` with component-only sync.

package/assets/generated/deployment/distribution/lean-poc-deploy.py

@@ -1,8 +1,8 @@
-#!/usr/bin/env python3
-from __future__ import annotations
-
-from lean_poc_deployment.entrypoint import main
-
-
-if __name__ == "__main__":
-    raise SystemExit(main())
+#!/usr/bin/env python3
+from __future__ import annotations
+
+from lean_poc_deployment.entrypoint import main
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/assets/generated/deployment/src/lean_poc_deployment/__init__.py

@@ -1,3 +1,3 @@
-"""Lean POC Deployment Kit."""
-
-__version__ = "0.1.0.dev0"
+"""Lean POC Deployment Kit."""
+
+__version__ = "0.1.0.dev0"

package/assets/generated/deployment/src/lean_poc_deployment/__main__.py

@@ -1,3 +1,3 @@
-from .entrypoint import main
-
-raise SystemExit(main())
+from .entrypoint import main
+
+raise SystemExit(main())

package/assets/generated/deployment/src/lean_poc_deployment/app_cli.py

@@ -1,140 +1,140 @@
-"""CLI for generic immutable application runtime deployment."""
-
-from __future__ import annotations
-
-import argparse
-import json
-import sys
-from typing import Any
-
-from .app_runtime import (
-    APP_DEPLOY_WRITE_PHRASE,
-    PRODUCTION_APP_DEPLOY_WRITE_PHRASE,
-    app_inventory,
-    apply_app_deploy,
-    deploy_write_phrase,
-    normalize_app_spec,
-    plan_app_deploy,
-)
-from .errors import DeploymentKitError
-from .sqlite_adapter import assert_app_spec_matches_persistence
-
-
-def _print(value: Any, *, as_json: bool) -> None:
-    if as_json:
-        print(json.dumps(value, indent=2, sort_keys=True))
-        return
-    if isinstance(value, dict):
-        for key, item in value.items():
-            if isinstance(item, (dict, list)):
-                print(f"{key}: {json.dumps(item, sort_keys=True)}")
-            else:
-                print(f"{key}: {item}")
-        return
-    print(value)
-
-
-def _parse_env(items: list[str]) -> list[tuple[str, str]]:
-    result: list[tuple[str, str]] = []
-    for item in items:
-        if "=" not in item:
-            raise DeploymentKitError("--env entries must use NAME=value form.")
-        key, value = item.split("=", 1)
-        result.append((key, value))
-    return result
-
-
-def _confirm(args: argparse.Namespace, phrase: str, action: str) -> None:
-    if args.yes:
-        return
-    entered = input(f"Type {phrase} to {action}: ").strip()
-    if entered != phrase:
-        raise DeploymentKitError(f"{action.capitalize()} was not authorized.")
-
-
-def build_parser() -> argparse.ArgumentParser:
-    parser = argparse.ArgumentParser(prog="lean-poc-deploy app")
-    sub = parser.add_subparsers(dest="command", required=True)
-
-    inventory = sub.add_parser(
-        "inventory",
-        help="Read Kit-managed application runtime ownership/readiness without writes",
-    )
-    inventory.add_argument("name")
-    inventory.add_argument("--json", action="store_true")
-
-    deploy = sub.add_parser(
-        "deploy",
-        help="Deploy one immutable application runtime without modifying routes",
-    )
-    deploy.add_argument("name")
-    deploy.add_argument("--owner-repo", required=True)
-    deploy.add_argument("--environment", required=True)
-    deploy.add_argument("--app-slug", required=True)
-    deploy.add_argument("--container-name", required=True)
-    deploy.add_argument("--image", required=True)
-    deploy.add_argument("--runtime-port", type=int, required=True)
-    deploy.add_argument("--health-path", required=True)
-    deploy.add_argument("--run-as", required=True)
-    deploy.add_argument(
-        "--persistence-mode",
-        choices=("none", "directory"),
-        required=True,
-    )
-    deploy.add_argument("--data-container-path")
-    deploy.add_argument(
-        "--env",
-        action="append",
-        default=[],
-        help="Non-secret runtime environment value in NAME=value form; repeat as needed",
-    )
-    deploy.add_argument("--json", action="store_true")
-    deploy.add_argument("--yes", action="store_true")
-    return parser
-
-
-def main(argv: list[str] | None = None) -> int:
-    args = build_parser().parse_args(argv)
-    try:
-        if args.command == "inventory":
-            _print(app_inventory(args.name), as_json=args.json)
-            return 0
-
-        spec = normalize_app_spec(
-            owner_repo=args.owner_repo,
-            environment=args.environment,
-            app_slug=args.app_slug,
-            container_name=args.container_name,
-            image=args.image,
-            runtime_port=args.runtime_port,
-            health_path=args.health_path,
-            run_as=args.run_as,
-            persistence_mode=args.persistence_mode,
-            data_container_path=args.data_container_path,
-            environment_variables=_parse_env(args.env),
-        )
-        assert_app_spec_matches_persistence(args.name, spec)
-        plan = plan_app_deploy(args.name, spec)
-        _print(
-            {key: value for key, value in plan.items() if key != "spec"},
-            as_json=False,
-        )
-        phrase = deploy_write_phrase(plan)
-        _confirm(
-            args,
-            phrase,
-            f"deploy {plan['appSlug']} ({plan['environment']}) on target {args.name}",
-        )
-        _print(apply_app_deploy(plan), as_json=args.json)
-        return 0
-    except DeploymentKitError as error:
-        print(f"ERROR: {error}", file=sys.stderr)
-        return 2
-
-
-__all__ = [
-    "APP_DEPLOY_WRITE_PHRASE",
-    "PRODUCTION_APP_DEPLOY_WRITE_PHRASE",
-    "build_parser",
-    "main",
-]
+"""CLI for generic immutable application runtime deployment."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from typing import Any
+
+from .app_runtime import (
+    APP_DEPLOY_WRITE_PHRASE,
+    PRODUCTION_APP_DEPLOY_WRITE_PHRASE,
+    app_inventory,
+    apply_app_deploy,
+    deploy_write_phrase,
+    normalize_app_spec,
+    plan_app_deploy,
+)
+from .errors import DeploymentKitError
+from .sqlite_adapter import assert_app_spec_matches_persistence
+
+
+def _print(value: Any, *, as_json: bool) -> None:
+    if as_json:
+        print(json.dumps(value, indent=2, sort_keys=True))
+        return
+    if isinstance(value, dict):
+        for key, item in value.items():
+            if isinstance(item, (dict, list)):
+                print(f"{key}: {json.dumps(item, sort_keys=True)}")
+            else:
+                print(f"{key}: {item}")
+        return
+    print(value)
+
+
+def _parse_env(items: list[str]) -> list[tuple[str, str]]:
+    result: list[tuple[str, str]] = []
+    for item in items:
+        if "=" not in item:
+            raise DeploymentKitError("--env entries must use NAME=value form.")
+        key, value = item.split("=", 1)
+        result.append((key, value))
+    return result
+
+
+def _confirm(args: argparse.Namespace, phrase: str, action: str) -> None:
+    if args.yes:
+        return
+    entered = input(f"Type {phrase} to {action}: ").strip()
+    if entered != phrase:
+        raise DeploymentKitError(f"{action.capitalize()} was not authorized.")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="lean-poc-deploy app")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    inventory = sub.add_parser(
+        "inventory",
+        help="Read Kit-managed application runtime ownership/readiness without writes",
+    )
+    inventory.add_argument("name")
+    inventory.add_argument("--json", action="store_true")
+
+    deploy = sub.add_parser(
+        "deploy",
+        help="Deploy one immutable application runtime without modifying routes",
+    )
+    deploy.add_argument("name")
+    deploy.add_argument("--owner-repo", required=True)
+    deploy.add_argument("--environment", required=True)
+    deploy.add_argument("--app-slug", required=True)
+    deploy.add_argument("--container-name", required=True)
+    deploy.add_argument("--image", required=True)
+    deploy.add_argument("--runtime-port", type=int, required=True)
+    deploy.add_argument("--health-path", required=True)
+    deploy.add_argument("--run-as", required=True)
+    deploy.add_argument(
+        "--persistence-mode",
+        choices=("none", "directory"),
+        required=True,
+    )
+    deploy.add_argument("--data-container-path")
+    deploy.add_argument(
+        "--env",
+        action="append",
+        default=[],
+        help="Non-secret runtime environment value in NAME=value form; repeat as needed",
+    )
+    deploy.add_argument("--json", action="store_true")
+    deploy.add_argument("--yes", action="store_true")
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    try:
+        if args.command == "inventory":
+            _print(app_inventory(args.name), as_json=args.json)
+            return 0
+
+        spec = normalize_app_spec(
+            owner_repo=args.owner_repo,
+            environment=args.environment,
+            app_slug=args.app_slug,
+            container_name=args.container_name,
+            image=args.image,
+            runtime_port=args.runtime_port,
+            health_path=args.health_path,
+            run_as=args.run_as,
+            persistence_mode=args.persistence_mode,
+            data_container_path=args.data_container_path,
+            environment_variables=_parse_env(args.env),
+        )
+        assert_app_spec_matches_persistence(args.name, spec)
+        plan = plan_app_deploy(args.name, spec)
+        _print(
+            {key: value for key, value in plan.items() if key != "spec"},
+            as_json=False,
+        )
+        phrase = deploy_write_phrase(plan)
+        _confirm(
+            args,
+            phrase,
+            f"deploy {plan['appSlug']} ({plan['environment']}) on target {args.name}",
+        )
+        _print(apply_app_deploy(plan), as_json=args.json)
+        return 0
+    except DeploymentKitError as error:
+        print(f"ERROR: {error}", file=sys.stderr)
+        return 2
+
+
+__all__ = [
+    "APP_DEPLOY_WRITE_PHRASE",
+    "PRODUCTION_APP_DEPLOY_WRITE_PHRASE",
+    "build_parser",
+    "main",
+]