@mriekki/lean 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,206 @@
+---
+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.
+argument-hint: "[optional problem summary]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Upstream Fix
+
+`/upstream-fix` is for a problem discovered while working in a consumer repository when the likely owner is shared Lean code rather than consumer product code.
+
+The governing rule is:
+
+```text
+discover in the consumer
+→ diagnose/prove in the consumer
+→ fix in the owning canonical repository
+→ deliver there
+→ sync the accepted shared commit back into the consumer
+→ verify again in the 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.
+
+## 1. Invocation authorization
+
+Invoking `/upstream-fix` authorizes:
+
+- read-only ownership/provenance inspection in the consumer;
+- classification of the problem to the owning layer;
+- 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.
+
+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.
+
+Normal review and `/deliver` occur later while focused on the owning canonical repository.
+
+## 2. Establish consumer provenance
+
+From the consumer root inspect, when present:
+
+- `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
+```
+
+Do not assume every generated-looking file is shared-owned. Use baseline managed-path records as the primary ownership evidence.
+
+## 3. Classify the owner
+
+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.
+
+Result:
+
+```text
+CONSUMER FIX
+Owner: current repository
+```
+
+Stop upstream routing and continue through 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:
+
+```text
+CORE BUG
+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:
+
+```text
+DEPLOYMENT BUG
+Owner: <repository recorded by DEPLOYMENT_BASELINE.json>
+```
+
+### 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 ownership is genuinely ambiguous, stop at `UPSTREAM OWNER UNCLEAR` and present the competing evidence. 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.
+
+Clearly report it as:
+
+```text
+TEMPORARY SHARED-MANAGED PROOF
+Consumer path: <path>
+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.
+
+## 5. Resolve a canonical local checkout
+
+For the classified owner, consider local candidates in this order:
+
+1. explicit path supplied by the human;
+2. an already-open workspace folder whose Git remote unambiguously matches the recorded canonical repository;
+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:
+
+- 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.
+
+## 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.
+
+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.
+
+If the consumer proof cannot be generalized safely, stop and reclassify or ask for a narrower canonical design rather than forcing the patch upstream.
+
+## 7. Handoff to canonical delivery
+
+After the upstream implementation is ready, report:
+
+```text
+UPSTREAM FIX READY
+
+Owner: <canonical repo>
+Branch: <branch>
+Consumer proof: <path/status>
+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.
+
+## 8. Adopt the accepted fix back into the consumer
+
+After the canonical PR is merged and its accepted default-branch CI is green:
+
+- 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.
+
+Then rerun the original consumer reproduction and baseline checks.
+
+A successful consumer retest is evidence that the shared fix works in context; it does not turn the consumer copy into the canonical source.
+
+## 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.
+
+Consumer-owned changes may be delivered normally when managed baselines are clean.
+
+## 10. Boundaries
+
+`/upstream-fix` never:
+
+- merges changes;
+- publishes releases/tags;
+- deploys production;
+- commits one change 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.

package/assets/generated/core/core/skills/wait-what/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: wait-what
+description: "The last explanation did not land. Re-explain it with enough context to understand where we are and what happens next."
+argument-hint: "[optional note about what was unclear]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Wait, What?
+
+Purpose: repair communication when the immediately preceding explanation did not land.
+
+This skill re-explains. It does not perform new engineering work.
+
+## 1. Use existing context first
+
+Re-pitch the immediately preceding explanation, or the specific unclear point named by the human.
+
+Prefer already-available conversation/repository context. Do not run commands, inspect new Git/GitHub state, modify files, or take the next workflow action merely to explain the prior response.
+
+If a safe explanation depends on information that is genuinely missing, say what is missing instead of inventing it.
+
+## 2. Use plain technical English
+
+Prefer:
+- short, direct sentences;
+- concrete nouns instead of vague pronouns;
+- one idea per sentence when possible;
+- familiar repository/work-item terminology;
+- explicit cause-and-effect language;
+- examples only when they make the explanation clearer.
+
+Use a Simplified-Technical-English style, but do not claim formal ASD-STE100 compliance.
+
+When repository glossary material exists, prefer its terminology. A glossary is helpful, not required.
+
+## 3. Re-establish orientation
+
+For a substantive explanation, cover only what helps:
+
+```text
+CURRENT CONTEXT
+Where we are and what led here.
+
+WHAT I MEANT
+The important point in simpler language.
+
+WHY IT MATTERS
+Why the point affects the current work or decision.
+
+WHAT HAPPENS NEXT
+The immediate next step, if there is one.
+```
+
+Do not force all headings for a tiny clarification. Keep the response proportional to the confusion.
+
+## 4. Respect human gates
+
+If the unclear explanation immediately preceded a human approval or consequential-action gate, complete the re-explanation before asking for that approval again.
+
+Do not treat `/wait-what` as approval to continue, write files, commit, push, merge, deploy, or call external systems.
+
+## 5. Route deeper needs without changing modes silently
+
+If the human actually needs:
+- current workflow-state orientation, suggest `/next-step`;
+- deeper concept teaching, suggest `/coach`;
+- a structured explanation of implementation changes, suggest `/code-walkthrough`;
+- an understanding check, suggest `/learning-review`.
+
+Do not silently switch into those modes unless the human asks.
+
+## 6. Boundaries
+
+`/wait-what` is:
+- read-only,
+- user-invoked,
+- non-blocking,
+- communication-focused,
+- usable during requirements, planning, implementation, review, delivery, setup, learning, or operations discussions.
+
+It does not create a new engineering workflow state.
+
+## Provenance
+
+Inspired by Matt Pocock's `wait-what` productivity skill in `mattpocock/skills` (MIT licensed). This Lean Core version is independently rewritten for repository-agnostic Human-in-the-Loop engineering workflows.

package/assets/generated/core/core/templates/FEATURE_BRIEF_TEMPLATE.md

@@ -0,0 +1,27 @@
+# Feature Brief — <Name>
+
+> Authority: <AUTHORITATIVE | SUPPLEMENTAL / EXPERIMENTAL>
+>
+> Jira relationship: <Epic / Story set / other>
+>
+> A Jira Epic is not automatically equivalent to this Feature Brief.
+
+## Problem / User Outcome
+
+## Scope
+
+## Non-Scope
+
+## Workflows
+
+## Cross-Story / Domain Rules
+
+## Dependencies
+
+## Related Jira Epics / Stories
+
+## Acceptance Summary
+
+## Open Decisions
+
+## Approval / Status

package/assets/generated/core/core/templates/PRODUCT_BRIEF_TEMPLATE.md

@@ -0,0 +1,27 @@
+# Product Brief — <Name>
+
+> Authority: <AUTHORITATIVE | SUPPLEMENTAL / EXPERIMENTAL>
+>
+> External system relationship: <for example Jira Epics/Stories remain primary>
+
+## Problem / Opportunity
+
+## Users / Stakeholders
+
+## Desired Outcomes
+
+## Scope
+
+## Non-Scope
+
+## Major Workflows / Capabilities
+
+## Domain / Policy Constraints
+
+## Success Measures
+
+## Related Jira Epics / Work Items
+
+## Open Decisions
+
+## Approval / Status

package/assets/generated/core/core/templates/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,37 @@
+<!--
+Internal PR-body scaffolding for the Lean delivery workflow.
+Populate from actual work-item, diff, test, review, and CI evidence.
+Do not mark checks complete unless the evidence was observed.
+-->
+
+## Work item
+
+<!-- ID and concise title -->
+
+## What changed
+
+-
+-
+-
+
+## Acceptance evidence
+
+- [ ] Relevant local formatting/build/test/checks pass
+- [ ] Relevant runtime/browser/container checks pass when applicable
+- [ ] GitHub Actions passes
+
+Mark items N/A in notes when they do not apply.
+
+## Review
+
+- [ ] Lean Reviewer completed when required by the work classification
+- [ ] Blocking findings resolved
+- [ ] Human final PR diff review completed
+
+## Known limitations / follow-up
+
+-
+
+## Notes
+
+<!-- Keep concise. Link to authoritative work-item docs instead of duplicating requirements. -->

package/assets/generated/core/core/templates/REQUIREMENTS_TEMPLATE.md

@@ -0,0 +1,17 @@
+# Detailed Requirements — <Work Item>
+
+> Use only when local detailed requirements are permitted and useful.
+>
+> Do not duplicate Jira/Issue authority without an explicit reason.
+
+## User / Engineering Outcomes
+
+## Domain / Engineering Requirements
+
+## Acceptance / Validation Scenarios
+
+## Open Decisions
+
+## Traceability
+
+## Authority / Approval

package/assets/generated/core/profiles/greenfield/lean-workspace.json

@@ -0,0 +1,12 @@
+{
+  "schemaVersion": 1,
+  "profile": "greenfield",
+  "workItemSource": "local-docs",
+  "productBriefs": {"mode": "authoritative"},
+  "featureBriefs": {"mode": "authoritative"},
+  "engineeringEnablers": {"mode": "authoritative"},
+  "localDetailedRequirements": {"mode": "authoritative-combined"},
+  "jira": {"accessMode": "none", "epics": "not-used"},
+  "delivery": {"pr": true, "explicitFinalPrAcceptance": true, "explicitMerge": true, "postMergeCi": "observe-if-configured"},
+  "productionReadiness": {"enabled": "when-production-in-scope"}
+}

package/assets/generated/core/tools/package/check_baseline.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+from pathlib import Path
+
+BASELINE_FILENAME = "CORE_BASELINE.json"
+
+
+def sha256_file(path: Path) -> str:
+    digest = hashlib.sha256()
+    with path.open("rb") as handle:
+        for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def resolve_managed_path(root: Path, rel: str) -> Path:
+    candidate = Path(rel)
+    if candidate.is_absolute() or ".." in candidate.parts:
+        raise ValueError(f"unsafe managed path: {rel}")
+    resolved = (root / candidate).resolve()
+    try:
+        resolved.relative_to(root)
+    except ValueError as exc:
+        raise ValueError(f"managed path escapes repository root: {rel}") from exc
+    return resolved
+
+
+def verify(root: Path, baseline_path: Path | None = None) -> int:
+    root = root.resolve()
+    baseline_path = baseline_path.resolve() if baseline_path else root / BASELINE_FILENAME
+    if not baseline_path.is_file():
+        print(f"MISSING baseline: {baseline_path}")
+        return 2
+
+    try:
+        baseline = json.loads(baseline_path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        print(f"INVALID baseline JSON: {exc}")
+        return 2
+
+    if baseline.get("schemaVersion") != 1:
+        print(f"UNSUPPORTED baseline schemaVersion: {baseline.get('schemaVersion')}")
+        return 2
+
+    managed = baseline.get("managedPaths")
+    if not isinstance(managed, list) or not managed:
+        print("INVALID baseline: managedPaths is missing or empty")
+        return 2
+
+    failures = 0
+    seen: set[str] = set()
+    for item in managed:
+        rel = item.get("path")
+        expected = item.get("sha256")
+        if not rel or not expected:
+            print(f"INVALID managed path entry: {item!r}")
+            failures += 1
+            continue
+        if rel in seen:
+            print(f"INVALID duplicate managed path: {rel}")
+            failures += 1
+            continue
+        seen.add(rel)
+        try:
+            path = resolve_managed_path(root, rel)
+        except ValueError as exc:
+            print(f"INVALID {exc}")
+            failures += 1
+            continue
+        if not path.is_file():
+            print(f"MISSING {rel}")
+            failures += 1
+            continue
+        actual = sha256_file(path)
+        if actual != expected:
+            print(f"DRIFT   {rel}")
+            failures += 1
+        else:
+            print(f"SAME    {rel}")
+
+    print()
+    if failures:
+        print(f"Core baseline integrity: FAIL ({failures} path(s))")
+        return 1
+    print(f"Core baseline integrity: PASS ({len(managed)} managed path(s))")
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Verify a consumer's Core-managed paths against CORE_BASELINE.json.")
+    parser.add_argument("--root", type=Path, default=Path.cwd(), help="Consumer repository root")
+    parser.add_argument("--baseline", type=Path, help="Optional explicit baseline file")
+    args = parser.parse_args()
+    return verify(args.root, args.baseline)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/assets/generated/core/tools/package/check_upstream.py

@@ -0,0 +1,171 @@
+#!/usr/bin/env python3
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import subprocess
+import urllib.error
+import urllib.parse
+import urllib.request
+from pathlib import Path
+from typing import Callable
+
+BASELINE_FILENAME = "CORE_BASELINE.json"
+
+
+class UpstreamUnavailable(RuntimeError):
+    pass
+
+
+def load_baseline(root: Path) -> dict:
+    path = root / BASELINE_FILENAME
+    if not path.is_file():
+        raise SystemExit(f"Missing {BASELINE_FILENAME}: {path}")
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as exc:
+        raise SystemExit(f"Invalid {BASELINE_FILENAME}: {exc}") from exc
+    required = ["coreRepository", "coreCommit", "coreVersion", "distribution"]
+    missing = [key for key in required if not data.get(key)]
+    if missing:
+        raise SystemExit(f"{BASELINE_FILENAME} missing required field(s): {', '.join(missing)}")
+    return data
+
+
+def github_get_json(url: str, token: str | None) -> dict:
+    headers = {
+        "Accept": "application/vnd.github+json",
+        "X-GitHub-Api-Version": "2022-11-28",
+        "User-Agent": "lean-agentic-core-upstream-check",
+    }
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    request = urllib.request.Request(url, headers=headers)
+    try:
+        with urllib.request.urlopen(request, timeout=20) as response:
+            return json.load(response)
+    except (urllib.error.HTTPError, urllib.error.URLError, TimeoutError) as exc:
+        raise UpstreamUnavailable(str(exc)) from exc
+
+
+def resolve_remote_head(repository: str, ref: str, token: str | None, fetch: Callable[[str, str | None], dict]) -> str:
+    quoted_ref = urllib.parse.quote(ref, safe="")
+    data = fetch(f"https://api.github.com/repos/{repository}/commits/{quoted_ref}", token)
+    sha = str(data.get("sha") or "").strip()
+    if not sha:
+        raise UpstreamUnavailable("GitHub response did not include a commit SHA")
+    return sha
+
+
+def compare_remote(
+    repository: str,
+    baseline_sha: str,
+    upstream_sha: str,
+    token: str | None,
+    fetch: Callable[[str, str | None], dict],
+) -> dict:
+    return fetch(
+        f"https://api.github.com/repos/{repository}/compare/{baseline_sha}...{upstream_sha}",
+        token,
+    )
+
+
+def resolve_local_head(core_path: Path, ref: str) -> str:
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(core_path), "rev-parse", ref],
+            check=True,
+            capture_output=True,
+            text=True,
+        )
+    except (OSError, subprocess.CalledProcessError) as exc:
+        raise UpstreamUnavailable(f"unable to resolve {ref!r} in {core_path}") from exc
+    return result.stdout.strip()
+
+
+def check_upstream(
+    root: Path,
+    *,
+    ref: str = "main",
+    token: str | None = None,
+    core_path: Path | None = None,
+    skip_if_unavailable: bool = False,
+    fetch: Callable[[str, str | None], dict] = github_get_json,
+) -> int:
+    root = root.resolve()
+    baseline = load_baseline(root)
+    repository = baseline["coreRepository"]
+    baseline_sha = baseline["coreCommit"]
+
+    try:
+        if core_path is not None:
+            upstream_sha = resolve_local_head(core_path.resolve(), ref)
+            comparison = None
+        else:
+            upstream_sha = resolve_remote_head(repository, ref, token, fetch)
+            comparison = None if upstream_sha == baseline_sha else compare_remote(
+                repository, baseline_sha, upstream_sha, token, fetch
+            )
+    except UpstreamUnavailable as exc:
+        if skip_if_unavailable:
+            print(f"Core upstream freshness: SKIP ({exc})")
+            return 0
+        print(f"Core upstream freshness: UNAVAILABLE ({exc})")
+        return 2
+
+    print(f"Consumer baseline: {baseline['coreVersion']} @ {baseline_sha}")
+    print(f"Upstream {ref}: {upstream_sha}")
+    if upstream_sha == baseline_sha:
+        print("Core upstream freshness: PASS")
+        return 0
+
+    if comparison:
+        status = comparison.get("status", "unknown")
+        ahead = comparison.get("ahead_by")
+        behind = comparison.get("behind_by")
+        if status in {"ahead", "identical"} and isinstance(ahead, int):
+            print(f"Core upstream freshness: STALE ({ahead} upstream commit(s) ahead)")
+        else:
+            details = []
+            if status:
+                details.append(f"status={status}")
+            if isinstance(ahead, int):
+                details.append(f"ahead_by={ahead}")
+            if isinstance(behind, int):
+                details.append(f"behind_by={behind}")
+            print("Core upstream freshness: DIVERGED" + (f" ({', '.join(details)})" if details else ""))
+    else:
+        print("Core upstream freshness: STALE")
+    return 1
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Check whether a consumer's recorded Lean Core commit is current upstream.")
+    parser.add_argument("--root", type=Path, default=Path.cwd(), help="Consumer repository root")
+    parser.add_argument("--ref", default="main", help="Core ref to compare against (default: main)")
+    parser.add_argument(
+        "--token-env",
+        default="LEAN_CORE_READ_TOKEN",
+        help="Environment variable containing a GitHub token for private Core access",
+    )
+    parser.add_argument("--core-path", type=Path, help="Use a local Core checkout instead of GitHub API")
+    parser.add_argument(
+        "--skip-if-unavailable",
+        action="store_true",
+        help="Exit successfully if upstream cannot be queried (useful when CI token is not configured)",
+    )
+    args = parser.parse_args()
+
+    token = os.getenv(args.token_env) or os.getenv("GITHUB_TOKEN")
+    return check_upstream(
+        args.root,
+        ref=args.ref,
+        token=token,
+        core_path=args.core_path,
+        skip_if_unavailable=args.skip_if_unavailable,
+    )
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())