@mriekki/lean 0.4.4 → 0.4.5

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

@@ -0,0 +1,116 @@
+---
+name: docs
+description: "Open or inspect the repository's current Lean project documentation site, ownership/authority map, and DB/System evidence freshness without creating a new workflow gate."
+argument-hint: "[open|check|build]"
+user-invocable: true
+disable-model-invocation: true
+---
+
+# Project Docs
+
+`/docs` is the front door to repository documentation. It is read-only with respect to project prose unless the human explicitly asks to edit documentation.
+
+## Purpose
+
+Use `/docs` to:
+
+- open the local project documentation site;
+- inspect documentation ownership/authority;
+- find the correct product, architecture, engineering, operations, learning, or ADR document;
+- see whether disposable System/DB evidence views are current, stale, unknown, or absent;
+- keep `/db-lab` and `/system-lab` easy to discover.
+
+Markdown remains canonical. The site is a generated local projection.
+
+## Default behavior
+
+When invoked without a mode:
+
+1. Read `docs/lean-docs.json` when present.
+2. Verify the documentation viewer exists at `tools/lean-docs/docs-site.py`.
+3. If it exists, use the repository-local Python/runtime convention to run:
+
+```text
+python tools/lean-docs/docs-site.py serve --root .
+```
+
+The viewer binds to loopback only and writes disposable output under `.lean/`.
+
+If the tool is unavailable, do not invent installation support. Fall back to a concise documentation map from repository Markdown and mention that the local viewer is unavailable in the current accepted baseline.
+
+## Modes
+
+### `/docs open`
+
+Equivalent to the default behavior.
+
+### `/docs check`
+
+Do not open a browser. Inspect:
+
+- `docs/lean-docs.json` validity when present;
+- missing listed documents;
+- ownership/authority declarations;
+- current Git commit;
+- System Lab cache freshness when evidence exists;
+- DB Lab cache availability/freshness only when evidence supports a conclusion.
+
+Do not treat a missing optional Lean-managed document as project corruption when Bootstrap generation and reusable-package application are still distinct phases.
+
+### `/docs build`
+
+Generate the disposable site without serving it:
+
+```text
+python tools/lean-docs/docs-site.py build --root . --out .lean/docs-site
+```
+
+This is a local derived artifact and should not normally be committed.
+
+## Current-by-default evidence
+
+System Lab can reconstruct architecture from repository evidence. The docs viewer may best-effort prepare the current System Lab projection when it starts and the tool is present.
+
+Database Lab is stricter: do not guess a database path. Show an existing DB projection or hand off to `/db-lab`; automatic generation is allowed only when a safe local development/test database path is already explicit.
+
+Never create a database, apply migrations, mutate application data, or inspect Production merely to populate documentation.
+
+## Ownership
+
+Respect `docs/lean-docs.json`:
+
+- `project` — project-owned prose and ADRs;
+- `lean` — reusable managed reference/process material;
+- `generated-evidence` — disposable projections.
+
+Do not silently rewrite `project` documents during `/docs` just because code changed. Surface likely documentation impact instead.
+
+## ADR behavior
+
+If current evidence reveals a consequential architecture choice that lacks a durable decision record, `/docs` may recommend creating an ADR from `docs/templates/ADR_TEMPLATE.md`.
+
+Recommendation is not approval. Do not invent or accept the decision for the human.
+
+## Output when not opening the site
+
+Prefer a compact result such as:
+
+```text
+PROJECT DOCS
+
+Entry: PROJECT_BRIEF.md
+Product authority: docs/product/PRODUCT_BRIEF.md
+Work-item authority: docs/work-items/...
+Current commit: abc1234
+
+System evidence: CURRENT / STALE / NOT GENERATED
+Database evidence: CURRENT / STALE / AVAILABLE-FRESHNESS-UNKNOWN / NOT GENERATED
+
+Useful:
+- /system-lab
+- /db-lab
+- /code-walkthrough
+- /learning-review
+```
+
+Documentation status is not a delivery gate unless an approved work item explicitly requires documentation as acceptance evidence.

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

@@ -1,6 +1,6 @@
 ---
 name: next-step
-description: Read-only orientation over work-item, Git, review, PR, PR CI, merge, post-merge default-branch CI, deployment readiness, and deployment handoff state.
+description: Read-only orientation over work-item, Git, review, PR, PR CI, merge, post-merge default-branch CI, deployment readiness, deployment handoff state, and optional documentation/learning surfaces.
 argument-hint: "[optional work-item ID or external key]"
 user-invocable: true
 disable-model-invocation: true
@@ -68,7 +68,7 @@ Use only states supported by observed evidence.
 
 Do not add a separate final-PR-acceptance state when the PR still exactly matches the already accepted local implementation. In that normal case, `/deliver` combines final acceptance and merge into the single `MERGE_READY` decision. If PR evidence changed materially, describe the required final PR review explicitly before returning to `MERGE_READY`.
 
-Do not add learning-only states such as `CODE_WALKTHROUGH_PENDING`. Optional coaching and labs do not change engineering delivery state.
+Do not add learning- or documentation-only states such as `CODE_WALKTHROUGH_PENDING` or `DOCS_UPDATE_PENDING`. Optional coaching, labs, and project documentation do not change engineering delivery state unless the approved work item explicitly makes documentation acceptance evidence.
 
 ## 3. Output
 
@@ -88,11 +88,12 @@ OPTIONS
 
 Only show relevant options. `/next-step` orients; it does not become another workflow database.
 
-## 4. Optional learning choices
+## 4. Optional documentation and learning choices
 
-When implementation is stable enough to learn from and the human appears interested in understanding the code, `/next-step` may offer learning choices without making them gates:
+When implementation is stable enough to understand or document, `/next-step` may offer these choices without making them gates:
 
 ```text
+/docs [open|check|build] — project documentation map/site and evidence freshness [READ ONLY]
 /code-walkthrough <scope> — guided changed-file explanation [READ ONLY]
 /learning-review <scope> — understanding assessment [READ ONLY]
 /coach <topic> — focused concept coaching [READ ONLY]
@@ -100,13 +101,17 @@ When implementation is stable enough to learn from and the human appears interes
 /system-lab [changes <work-item>] — current architecture/runtime/failure/design evidence [READ ONLY]
 ```
 
-Prefer `/code-walkthrough` when the user wants to understand what changed across an implementation. Prefer `/db-lab` when the question depends on concrete schema/query/index/ORM evidence. Prefer `/system-lab` when it depends on architecture, runtime flows, APIs, dependencies, failure behavior, scale, messaging, observability, security, deployment, testing, or system-design tradeoffs.
+Prefer `/docs` when the user wants the coherent project briefing, documentation map, ADR/architecture/operations references, or current DB/System projection status. Prefer `/code-walkthrough` when the user wants to understand what changed across an implementation. Prefer `/db-lab` when the question depends on concrete schema/query/index/ORM evidence. Prefer `/system-lab` when it depends on architecture, runtime flows, APIs, dependencies, failure behavior, scale, messaging, observability, security, deployment, testing, or system-design tradeoffs.
 
-When a known work-item diff materially touches one of those evidence areas, make the corresponding `changes <work-item>` option visibly relevant. Do not claim a runtime or physical-schema change solely because a file was touched.
+When a known work-item diff materially touches documentation-sensitive areas, make the impact visible without inventing a gate. Examples include public contracts, architecture/dependencies, persistence/schema, deployment/environments, developer workflow, test strategy, or a consequential architecture tradeoff that may deserve an ADR.
 
-Labs inspect current evidence when invoked. Do not tell the human to refresh or rebuild a generated diagram.
+Safe generated projections may be prepared automatically. Do not silently rewrite project-owned prose or accept an ADR on the human's behalf merely because implementation evidence changed.
 
-Do not recommend any learning activity as mandatory before `/deliver`.
+When a known work-item diff materially touches a DB/System evidence area, make the corresponding `changes <work-item>` option visibly relevant. Do not claim a runtime or physical-schema change solely because a file was touched.
+
+Labs inspect current evidence when invoked. Do not tell the human to refresh, rebuild, or manually synchronize a generated diagram.
+
+Do not recommend any documentation or learning activity as mandatory before `/deliver` unless the approved work item explicitly requires it.
 
 ## 5. Delivery handoff
 
@@ -148,7 +153,7 @@ Never merge from `/next-step` merely because CI is green.
 After merge:
 - if required default-branch CI is pending, return to `/deliver` to resume observation/finalization;
 - if failed, inspect/diagnose;
-- if green and branch finalization is safe/complete, report delivery complete and optional relevant learning follow-ups without changing the delivery state.
+- if green and branch finalization is safe/complete, report delivery complete and optional relevant documentation/learning follow-ups without changing the delivery state.
 
 ## 6. Deployment handoff
 
@@ -182,4 +187,4 @@ Do not infer readiness of one environment from another. Production is never an i
 
 Do not auto-run Reviewer, auto-run learning activities, auto-merge, auto-deploy, pin/select a model, or maintain duplicate workflow state outside Git/GitHub and the configured work-item/readiness authority.
 
-Generating a disposable read-only learning workbench is not the same as auto-running a learning activity or proving understanding. `/deliver` may prepare such artifacts best-effort after successful delivery when safe and relevant; learning itself remains optional.
+Generating a disposable read-only documentation or learning workbench is not the same as performing a learning activity, approving documentation prose, or proving understanding. `/deliver` may prepare such artifacts best-effort after successful delivery when safe and relevant; learning itself remains optional.

package/assets/generated/core/core/skills/tear-down/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: tear-down
-description: "Guided destructive environment cleanup for local, Staging, Production, or all supported POC scopes. Preserves exact ownership boundaries, separate Production-data authorization, and delegates deletion mechanics to repository-provided tooling."
-argument-hint: "[local|staging|production|all]"
+description: "Guided destructive cleanup for local state, one exact named logical environment, or all explicitly configured POC environments. Preserves ownership boundaries and separate Production-data authorization."
+argument-hint: "[local|<environment>|all]"
 user-invocable: true
 disable-model-invocation: true
 ---
@@ -10,129 +10,169 @@ disable-model-invocation: true
 
 `/tear-down` is the human-facing destructive cleanup workflow for repository-owned POC environments and local runtime state.
 
-The skill owns scope selection, read-only preflight, destructive preview, and Human-in-the-Loop authorization. Repository-provided deployment tooling owns teardown mechanics.
+The skill owns scope selection, read-only preflight, destructive preview, and Human-in-the-Loop authorization. Repository-provided deployment tooling owns deletion mechanics.
+
+Logical environments are not limited to Staging and Production. A repository may define `demo`, `qa`, `staging`, `production`, or another safe named environment.
 
 Do not implement Docker, filesystem, route, database, registry, or host cleanup directly in the skill when an approved repository command exists.
 
 ## 1. Begin read-only
 
-Invocation starts read-only.
-
 Read only the minimum repository context needed to identify:
 
-- the repository's approved tear-down entry point;
-- the canonical repository/application identity used by that entry point;
-- configured Staging and Production environment-to-target bindings when those scopes are available;
-- the exact local image/package identity used to identify POC-owned local Docker state;
-- the currently supported tear-down scopes and their ownership boundaries.
+- approved tear-down entry point and installed Deployment Kit version/baseline when applicable;
+- canonical repository/application identity;
+- repository-defined logical environments, their roles/purposes, and explicit target bindings;
+- which selected environments are Production-class;
+- exact local image/package identity used for POC-owned workstation Docker cleanup;
+- supported tear-down scopes and ownership boundaries.
+
+Do not assume:
 
-Do not assume script paths, container names, volume names, environment bindings, target addresses, or package coordinates unless the repository establishes them.
+- Staging/Production are the only environments;
+- Staging and Production use separate physical machines;
+- `all` always means exactly local + Staging + Production;
+- a local package exists;
+- remote target addresses/aliases;
+- container/volume names not established by the deterministic tool.
 
-If the repository does not provide an approved deterministic tear-down command for the requested scope, stop. Do not improvise destructive shell commands.
+If the repository does not provide an approved deterministic command for the requested destructive scope, stop. Do not improvise shell commands.
 
-## 2. Select the scope explicitly
+## 2. Select exact scope
 
-Supported generic scope names are:
+Generic scope model:
 
 ```text
 local
-staging
-production
+<one exact repository-defined named environment>
 all
 ```
 
-If the invocation did not name a scope, present only scopes the current repository actually supports and ask the human to select one.
+If no scope is named, present only scopes the current repository actually supports.
 
 Rules:
 
-- never silently default to `production` or `all`;
-- never infer destructive scope from a previous deployment or prior conversation;
-- never widen a requested scope after a failure;
-- `all` means all supported tear-down scopes for this one repository/POC, not machine-wide cleanup;
-- selecting a scope does not itself authorize deletion.
+- never silently default to a Production environment or `all`;
+- never infer destructive scope from a prior deploy/conversation;
+- never widen scope after failure;
+- `all` means all explicitly configured/supplied scopes for this one POC, never machine-wide cleanup;
+- selecting scope never authorizes deletion.
+
+A named environment is independently targetable even when multiple environments share one physical target/failure domain.
+
+If a named environment is unsupported/unconfigured, fail explicitly rather than falling back to another environment on the same host.
 
-If a named scope is unsupported or not configured, fail explicitly.
+## 3. Resolve ownership and Production classification
 
-## 3. Resolve exact ownership and target evidence
+Before an authorization gate, resolve non-secret ownership/evidence required by the installed tear-down contract.
+
+For local cleanup identify the exact POC-owned local runtime/package boundary.
+
+For each selected remote environment identify:
+
+```text
+environment name
+role/purpose (including Production classification)
+configured logical target
+repository/application identity
+ownership markers required by the deterministic tool
+```
 
-Before presenting an authorization gate, resolve the non-secret ownership evidence required by the repository's tear-down contract.
+The literal environment name `production` should be treated as Production when the installed Deployment Kit does so for compatibility. Repositories may also classify another named environment as Production; pass that classification only through the installed tool's supported contract (for example `--production-environment <name>`).
 
-For local cleanup, this should identify the exact POC-owned local runtime/package boundary. For remote environments, this should identify the exact named environment, configured logical target, repository/application identity, and any ownership markers the deterministic tear-down tool verifies.
+Physical colocation never merges ownership. `staging` cleanup must not remove `production` because both bind to the same VPS.
 
-Preserve the repository's shared-resource boundary. Normal POC tear-down must not broaden into deletion of shared platform infrastructure, unrelated POCs, workstation trust/credentials, or registry packages unless the repository defines a separate explicit lifecycle operation for those resources.
+Preserve shared-resource boundaries. Normal POC tear-down must not broaden into shared platform infrastructure, unrelated POCs/environments, workstation trust/credentials, or registry packages unless a separate explicit lifecycle operation owns those resources.
 
-If ownership is ambiguous, a target binding changed, host identity cannot be verified, or the underlying tool reports mismatched ownership, stop without deletion.
+If ownership is ambiguous, a binding/evidence set changed, host identity cannot be verified where required, or the tool reports mismatched ownership, stop without deletion.
 
-## 4. Present the destructive preview
+## 4. Present exact destructive preview
 
-Before authorization, show what will be removed and what will be preserved using the repository's actual contract.
+Show what will be removed and preserved using current repository/tool evidence.
 
-A typical preview is:
+Example:
 
 ```text
 TEAR-DOWN READY
 
-Scope: <local|staging|production|all>
+Scope: <local|demo|staging|production|other|all>
 Repository/app: <verified identity>
-Staging target: <verified logical target or not selected>
-Production target: <verified logical target or not selected>
-Local package/runtime identity: <exact identity or not selected>
+Selected environments:
+  <env> → <logical target> — <Production/non-Production>
+Local package/runtime: <exact identity or NOT SELECTED>
 
 Will remove:
-  <repository-supported owned resources>
+  <tool/repository-supported owned resources for exactly these scopes>
 
 Will preserve:
-  <shared/unrelated resources established by the repository contract>
+  <shared/unrelated environments/resources>
 ```
 
-For Deployment-Kit consumers, expected behavior includes:
+For current Deployment-Kit consumers:
 
-- `local` — exact-package local containers/images and Docker-managed anonymous volumes attached to those owned containers;
-- `staging` — the owned Staging route, runtime, release/evidence state, persistent application data, and backups;
-- `production` — the owned Production route, runtime, release/evidence state, persistent application data, and backups;
-- `all` — Staging + Production + local for the selected POC only.
+- `local` — exact-package local containers/images and Docker-managed anonymous volumes attached to those exact containers;
+- `<environment>` — only that exact owned route/runtime/release/evidence/persistent-data/backup scope;
+- `all` — all explicitly supplied named environment bindings plus optional exact-package local state when supplied.
 
-Do not promise deletion of named/shared Docker volumes or other resources unless the repository has an independent ownership model that safely proves they belong to this POC.
+Do not promise deletion of named/shared Docker volumes or other resources unless independent ownership can be proven.
 
-## 5. Require the destructive authorization gate
+When selected logical environments share one physical target, say so in the preview so the user can verify that the deletion set remains environment-scoped.
 
-Every modifying tear-down requires one explicit bounded authorization for the exact previewed scope and evidence:
+## 5. Authorization gates
+
+Every modifying tear-down requires:
 
 ```text
 [POC TEAR DOWN]
 ```
 
-For `production` or `all`, persistent Production data is part of the requested destructive scope. Require an additional independent authorization:
+Additionally, whenever **any selected environment is Production-class**, require:
 
 ```text
 [PRODUCTION DATA DELETE]
 ```
 
-The Production-data authorization is required even when Production was previously deployed, tested, approved, or selected. Deployment authorization does not authorize data deletion.
+Do not tie the Production-data gate only to literal scope strings `production` or `all`. It depends on the resolved deletion set and Production classification.
+
+Deployment authorization, prior testing, CI, merge approval, environment selection, and physical colocation do not authorize persistent Production data deletion.
+
+If repository/app identity, selected environments, Production classification, target binding, ownership evidence, or deletion set changes after preview, require renewed review/authorization.
+
+## 6. Execute only repository-provided command
+
+After exact authorization, invoke only the approved tear-down command with the exact selected scopes and resolved inputs.
 
-If the resolved repository/app identity, target binding, ownership evidence, or deletion set materially changes after the preview, stop and require renewed review and authorization.
+For generalized Deployment Kit consumers this may include repeated explicit environment bindings such as:
 
-## 6. Execute only the approved repository command
+```text
+--environment-target demo=<target>
+--environment-target staging=<target>
+--environment-target production=<target>
+```
+
+and, when needed for a non-literal Production environment:
 
-After the required authorization phrase or phrases are explicitly provided, invoke only the repository-approved tear-down command with the exact selected scope and resolved inputs.
+```text
+--production-environment prod-east
+```
 
-Pass authorization through only when the repository command expects the same bounded contract. Do not translate one approval into broader deletion authority.
+Do not manually substitute another binding format if the installed version has a different contract; inspect the distributed tool/help/docs first.
 
-Do not add machine-wide Docker prune, shared-network removal, shared Caddy/Avahi removal, unrelated branch/repository cleanup, registry-package deletion, host reprovisioning, target rebinding, or secret/trust cleanup unless those operations are separately defined and explicitly authorized by the repository.
+Never add machine-wide Docker prune, shared-network/Caddy/Avahi removal, unrelated environment cleanup, registry-package deletion, host reprovisioning, target rebinding, or secret/trust deletion unless separately defined and explicitly authorized.
 
-If the deterministic command stops partway through `all`, report the completed and remaining scopes. Do not compensate by manually deleting the remainder.
+If an aggregate `all` operation stops partway, report completed/remaining scopes. Do not manually compensate by deleting the rest.
 
-## 7. Verify and report the outcome
+## 7. Verify/report outcome
 
-Use repository-provided evidence/status commands when available. Report only what the evidence supports, including:
+Use repository-provided evidence/status commands when available. Report only supported evidence:
 
 - requested scope;
 - repository/application identity;
-- environments/targets actually processed;
-- local runtime state actually processed;
-- whether persistent Production data was included;
+- exact logical environments/targets processed;
+- Production-class environments included;
+- local runtime state processed;
 - removed versus already-absent resources;
-- any failure point or remaining scope after a partial stop;
-- confirmation that shared/unrelated resources were preserved when the repository provides evidence for that claim.
+- failure point/remaining scopes after a partial stop;
+- preservation of shared/unrelated resources only when evidence supports it.
 
-The operation should remain safe to rerun for already-absent owned resources when the repository's tear-down contract says it is idempotent.
+The operation should remain safe to rerun for already-absent owned resources when the installed tear-down contract is idempotent.

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

@@ -0,0 +1,41 @@
+# ADR-NNN — <Decision title>
+
+Status: **PROPOSED**
+
+Date: `<YYYY-MM-DD>`
+
+## Context
+
+What engineering/product constraint or tradeoff requires a durable decision?
+
+## Decision
+
+What was decided?
+
+Do not mark an ADR accepted until the human/repository process has actually accepted the decision.
+
+## Alternatives considered
+
+- `<alternative>` — why it was considered and why it was not selected.
+- `<alternative>` — why it was considered and why it was not selected.
+
+## Tradeoffs / consequences
+
+### Benefits
+
+- `<benefit>`
+
+### Costs / risks
+
+- `<cost or risk>`
+
+## Evidence / links
+
+- Work item: `<ID or link>`
+- Relevant code/config: `<path>`
+- System Lab scenario/component: `<reference when useful>`
+- Other docs: `<link>`
+
+## Follow-up / review trigger
+
+What future condition should cause this decision to be revisited?