@mriekki/lean 0.4.3 → 0.4.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (35) hide show
  1. package/assets/components.json +3 -3
  2. package/assets/core/distribution.json +8 -0
  3. package/assets/deployment/distribution.json +2 -0
  4. package/assets/generated/ASSEMBLY.json +73 -23
  5. package/assets/generated/core/core/instructions/lean-docs.instructions.md +33 -2
  6. package/assets/generated/core/core/instructions/lean-workflow.instructions.md +42 -0
  7. package/assets/generated/core/core/learning/DIAGRAM_GUIDE.md +46 -6
  8. package/assets/generated/core/core/learning/ENGINEERING_LEARNING_WORKBOOK.md +29 -6
  9. package/assets/generated/core/core/learning/LEARNING_MAP.md +37 -2
  10. package/assets/generated/core/core/learning/LEARNING_PROGRESS.md +15 -7
  11. package/assets/generated/core/core/learning/SYSTEM_DESIGN_DRILLS.md +299 -19
  12. package/assets/generated/core/core/process/COACHING_GUIDE.md +35 -2
  13. package/assets/generated/core/core/process/DATABASE_LEARNING_WORKBENCH.md +153 -102
  14. package/assets/generated/core/core/process/DEPLOYMENT_ENABLEMENT.md +108 -71
  15. package/assets/generated/core/core/process/LEAN_ENGINEERING_GUIDE.md +317 -0
  16. package/assets/generated/core/core/process/PROJECT_DOCUMENTATION_FRAMEWORK.md +324 -0
  17. package/assets/generated/core/core/process/SYSTEM_DESIGN_LEARNING_WORKBENCH.md +520 -0
  18. package/assets/generated/core/core/skills/coach/SKILL.md +31 -4
  19. package/assets/generated/core/core/skills/db-lab/SKILL.md +59 -16
  20. package/assets/generated/core/core/skills/deliver/SKILL.md +77 -5
  21. package/assets/generated/core/core/skills/deploy/SKILL.md +164 -121
  22. package/assets/generated/core/core/skills/deployment-readiness/SKILL.md +223 -250
  23. package/assets/generated/core/core/skills/docs/SKILL.md +116 -0
  24. package/assets/generated/core/core/skills/next-step/SKILL.md +21 -6
  25. package/assets/generated/core/core/skills/system-lab/SKILL.md +333 -0
  26. package/assets/generated/core/core/skills/tear-down/SKILL.md +101 -61
  27. package/assets/generated/core/core/templates/ADR_TEMPLATE.md +41 -0
  28. package/assets/generated/core/tools/docs_site/docs_site.py +382 -0
  29. package/assets/generated/core/tools/system_lab/system_workbench.py +243 -0
  30. package/assets/generated/deployment/src/lean_poc_deployment/entrypoint.py +5 -1
  31. package/assets/generated/deployment/src/lean_poc_deployment/local_cli.py +112 -0
  32. package/assets/generated/deployment/src/lean_poc_deployment/local_runtime.py +523 -0
  33. package/assets/generated/deployment/src/lean_poc_deployment/teardown.py +49 -35
  34. package/assets/generated/deployment/src/lean_poc_deployment/teardown_cli.py +31 -12
  35. package/package.json +1 -1
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: deployment-readiness
3
- description: Guided readiness for any named deployment environment. Discovers current state, verifies access and pre-deploy prerequisites, repairs only missing setup, and hands environments that are ready to deploy to /deploy.
3
+ description: Guided readiness for any named deployment environment. Resolves logical topology first, verifies only placement-relevant prerequisites, treats deferred deployment as intentional state, and hands ready environments to /deploy.
4
4
  argument-hint: "[environment] | status [environment]"
5
5
  user-invocable: true
6
6
  disable-model-invocation: true
@@ -8,337 +8,291 @@ disable-model-invocation: true
8
8
 
9
9
  # Deployment Readiness
10
10
 
11
- `/deployment-readiness` is the reusable operational workflow for preparing named deployment environments such as Staging, Production, test, demo, or another repository-approved environment.
11
+ `/deployment-readiness` prepares one named deployment environment without assuming that an environment is a physical computer.
12
12
 
13
- It is not the application deployment executor and it is not production-only. Production is an environment role/policy with stronger gates, not a separate readiness mechanism.
13
+ Logical environment purpose/role, placement, isolation, exposure, and concrete target/provider binding are separate facts.
14
14
 
15
- The normal human-facing invocation is:
15
+ Normal invocation:
16
16
 
17
17
  ```text
18
18
  /deployment-readiness <environment>
19
19
  ```
20
20
 
21
- The workflow is state-driven and resumable. It discovers whether the environment is unconfigured, partially configured, access-ready, platform-ready, or ready to deploy, then continues from the furthest safe observed state. Do not require the human to choose `discovery`, `enable`, or `resume` modes.
22
-
23
- For a read-only overview, support:
21
+ Read-only overview:
24
22
 
25
23
  ```text
26
24
  /deployment-readiness status [environment]
27
25
  ```
28
26
 
29
- For compatibility, if an older invocation includes a deployment-enabler ID and/or the legacy `discovery`, `enable`, or `resume` token, normalize it to the same state-driven workflow rather than forcing the human to restart. Do not advertise those legacy forms as the normal interface.
30
-
31
- ## 1. Resolve minimum context
32
-
33
- Read `.github/lean-workspace.json` when present plus only the relevant deployment enabler requirements/decisions/readiness record, release/deployment guidance, environment configuration contract, current package/deployment baselines, and repository-provided deployment tooling.
34
-
35
- A deployment-enabler ID may be inferred from current repository/work-item context when it is unambiguous. Do not force the human to restate an already-known ID.
36
-
37
- Do not assume:
38
-
39
- - there is only one deployment environment;
40
- - an environment named `production` exists;
41
- - a particular local configuration filename;
42
- - target OS/runtime/hostname/IP;
43
- - SSH alias or discovery mechanism;
44
- - certificate model or hosting environment.
27
+ Production is a policy/authorization role with stronger gates, not a separate readiness mechanism. Do not silently default to Production.
45
28
 
46
- If the invocation does not name an environment and more than one configured environment exists, ask the human to select one. Never silently default to Production.
29
+ ## 1. Resolve current repository topology first
47
30
 
48
- ## 2. Human-facing information model
31
+ Read `.github/lean-workspace.json` when present plus only the relevant deployment requirements/decisions/readiness record, `POC_BOOTSTRAP.json` deployment topology, release/deployment guidance, current package/deployment baselines, and repository-provided deployment tooling.
49
32
 
50
- Keep the interaction centered on facts a person normally knows about the selected environment's machine:
33
+ Resolve, when repository evidence provides them:
51
34
 
52
35
  ```text
53
- environment name / role
54
- hostname or IP address
55
- SSH/deployment user when applicable
56
- SSH port when non-default or already configured
57
- target OS when known
36
+ environment name
37
+ role / purpose
38
+ placement
39
+ isolation
40
+ exposure
41
+ binding state
42
+ adapter
43
+ target/provider binding
44
+ failure domain
58
45
  ```
59
46
 
60
- Deployment tooling may internally require identifiers and files such as a logical target name, `targetName`, SSH alias, profile path, identity-file path, known-hosts path, address override, or trust record. Those are implementation details.
61
-
62
- **Do not ask the human to invent or transcribe `targetName`, an SSH alias, profile filename/path, known-hosts filename/path, or similar deployment-tool plumbing when the workflow can discover, reuse, or derive it.**
47
+ Never infer missing topology merely from an environment name.
63
48
 
64
- Do not lead with questions such as `What is the logical target name?`. If an internal saved-machine/profile identifier must eventually be chosen and cannot be derived safely from existing state or confirmed machine facts, explain it in plain language, recommend a sensible stable value, and ask only at that point.
65
-
66
- Never use an application-specific example to imply that a reusable machine identity belongs to one POC. A machine/profile may legitimately be reused by multiple POCs while each POC keeps independent environment bindings, application state, data, routes, and deployment evidence.
49
+ Do not assume:
67
50
 
68
- ### Application route/address defaults
51
+ - a second computer exists;
52
+ - the developer is on a trusted/home LAN;
53
+ - Staging or Production exists;
54
+ - Staging and Production use different physical machines;
55
+ - deployment uses SSH;
56
+ - a remote target exists;
57
+ - a managed provider is supported;
58
+ - a deferred binding is broken configuration.
69
59
 
70
- Keep the machine's hostname/address separate from the application's route hostname. A target such as `server.local` may host many POCs, while each application owns its own route aliases.
60
+ If more than one environment exists and the invocation does not select one, ask the human to choose one.
71
61
 
72
- When the repository or installed deployment tooling defines a deterministic application-route convention from stable inputs such as `appSlug + environment`, derive and present that exact conventional set before asking for a free-form hostname. Treat the derived values as recommended defaults for confirmation, not as permission to register or change a route.
62
+ ## 2. Placement determines the readiness branch
73
63
 
74
- For example, if the installed trusted-LAN deployment contract defines environment-scoped aliases such as:
64
+ After local read-only discovery, route to exactly one placement branch:
75
65
 
76
66
  ```text
77
- <app-slug>-<environment>.local
78
- <app-slug>.<environment>.local
67
+ workstation
68
+ remote-target
69
+ managed-service
70
+ deferred
79
71
  ```
80
72
 
81
- present the concrete derived values in plain language:
73
+ If older repositories lack the richer topology fields, infer the minimum compatible branch only from explicit legacy deployment configuration. For example, an explicit SSH target binding can establish `remote-target`; an environment name alone cannot.
82
74
 
83
- ```text
84
- STAGING APPLICATION ADDRESS
75
+ ### A. Workstation placement
85
76
 
86
- Recommended defaults:
87
- <derived alias 1>
88
- <derived alias 2>
77
+ A workstation environment is local application deployment, not remote-machine onboarding.
89
78
 
90
- 1. Use these defaults — recommended
91
- 2. Choose different hostnames
79
+ For the current reusable `workstation-container` adapter:
80
+
81
+ ```text
82
+ placement: workstation
83
+ isolation: container
84
+ exposure: loopback
92
85
  ```
93
86
 
94
- Do not ask `What route hostname(s) should this environment use?` while a repository/tool-owned deterministic default is available and no collision or policy conflict has been observed.
87
+ Readiness should inspect only relevant non-secret local facts such as:
95
88
 
96
- If the installed convention requires multiple compatibility aliases, preserve the complete default set. Do not silently drop one alias. If the convention defines an optional short alias with a larger collision surface, do not infer or add it; present it only when the repository/tool contract calls for an explicit opt-in.
89
+ - compatible Docker CLI/engine availability;
90
+ - repository/materialized `lean-poc-deploy local` support;
91
+ - exact immutable application image/artifact identity when already built/published;
92
+ - requested host/runtime port and health path when project-owned deployment facts exist;
93
+ - local port/Lean-container ownership collision evidence;
94
+ - persistence path/ownership prerequisites when applicable;
95
+ - Production-specific policy if this logical environment is Production.
97
96
 
98
- If the user rejects the defaults, or a read-only collision/policy check shows they cannot be used, ask for the smallest unresolved custom value and validate it through the installed tool's hostname contract.
97
+ Do **not** ask for hostname, SSH user, SSH port, target OS, target profile, host trust, Caddy route, Avahi, or remote credentials for a workstation-container environment.
99
98
 
100
- Selecting or confirming application route hostnames is configuration/readiness work only. It never authorizes DNS changes, route registration, Caddy changes, or another remote write; those retain their repository/tool-specific write gate.
99
+ The current reusable adapter is loopback-only. Readiness must not widen it to LAN/public exposure or suggest that loopback readiness satisfies a shareable/public deployment outcome.
101
100
 
102
- ## 3. Discover first, then ask only for missing facts
101
+ A successful workstation readiness handoff may look like:
103
102
 
104
- Invocation begins read-only.
103
+ ```text
104
+ ENVIRONMENT READY TO DEPLOY
105
105
 
106
- Before asking environment-specific setup questions, inspect available non-secret local/repository state to determine whether the selected environment is already configured on this workstation. Use repository-provided readiness helpers and installed deployment tooling when available.
106
+ Environment: Demo
107
+ Role: non-production
108
+ Placement: workstation
109
+ Isolation: container
110
+ Exposure: loopback
111
+ Docker: READY
112
+ Artifact: <exact immutable identity when required>
113
+ Port ownership: AVAILABLE
114
+ Persistence prerequisites: READY / NOT APPLICABLE
115
+ Security blockers: NONE
107
116
 
108
- Local discovery may inspect, as applicable:
117
+ POST-DEPLOY VALIDATION PENDING
118
+ Loopback route/health evidence is established by /deploy.
109
119
 
110
- - configured named environments and their roles;
111
- - existing environment-to-machine/target binding;
112
- - user-scoped deployment target/profile metadata;
113
- - hostname/address/discovery data already recorded;
114
- - SSH/deployment user and port metadata;
115
- - expected target OS;
116
- - existing readiness evidence;
117
- - whether required key/trust/profile files exist, without exposing secret contents.
120
+ NEXT
121
+ /deploy demo
122
+ ```
123
+
124
+ ### B. Remote-target placement
118
125
 
119
- Do not probe the remote machine merely to fill in this summary. Remote checks have their own authorization below.
126
+ Use the existing strict remote-target workflow.
120
127
 
121
- Classify the selected environment locally as one of:
128
+ Keep these concepts separate:
122
129
 
123
130
  ```text
124
- CONFIGURED — enough local state exists to attempt verification
125
- PARTIAL — some setup exists but required local state is missing/inconsistent
126
- NOT CONFIGURED — no usable workstation setup exists for this environment
131
+ named environment
132
+ → environment role/policy
133
+ → logical target binding
134
+ → current address/discovery
135
+ → independently verified host identity
127
136
  ```
128
137
 
129
- ### Existing configuration
130
-
131
- When usable configuration already exists, show the simple known facts and ask for confirmation instead of asking the human to reconstruct them:
138
+ Human-facing machine facts normally include:
132
139
 
133
140
  ```text
134
- STAGING SETUP FOUND
135
-
136
- Hostname/address: <known value>
137
- SSH user: <known value or not applicable>
138
- SSH port: <known/non-default value when useful>
139
- Target OS: <known/expected value when useful>
140
- Local setup: CONFIGURED
141
-
142
- 1. Yes — verify connectivity and identity [REMOTE READ ONLY]
143
- 2. Something changed — update the facts
144
- 3. Reconfigure/repair this PC
145
- 4. Stop
141
+ hostname or IP address
142
+ SSH/deployment user when applicable
143
+ SSH port when non-default or already configured
144
+ target OS when known
146
145
  ```
147
146
 
148
- Use the actual selected environment name rather than hardcoding `Staging`.
147
+ Internal target/profile identifiers, SSH aliases, identity-file paths, known-hosts paths, and trust records are implementation details. Do not ask the human to invent or transcribe them when repository/Deployment-Kit tooling can discover, reuse, or derive them.
149
148
 
150
- If a hostname and a currently observed/cached IP are both available, they may both be shown. Make clear that an address is connectivity information, not trusted host identity.
149
+ A remote machine/profile may be reused by multiple POCs or multiple logical environments. Each POC/environment still retains independent runtime, route, data, evidence, and policy identity.
151
150
 
152
- ### Partial configuration
151
+ Before asking questions, inspect available non-secret local state:
153
152
 
154
- Show what is already known and identify the smallest missing piece. Do not restart onboarding or ask for values that are already present and internally consistent.
153
+ - environment-to-target binding;
154
+ - user-scoped target/profile metadata;
155
+ - address/discovery data;
156
+ - SSH/deployment user/port;
157
+ - expected target OS;
158
+ - key/trust/profile presence without exposing secret contents;
159
+ - prior readiness evidence.
155
160
 
156
- Examples:
161
+ Classify local remote-target setup as:
157
162
 
158
163
  ```text
159
- Hostname/address: server.example.local
160
- SSH user: deploy
161
- Missing: trusted host identity
164
+ CONFIGURED
165
+ PARTIAL
166
+ NOT CONFIGURED
162
167
  ```
163
168
 
164
- or:
169
+ When configured, show known simple facts for confirmation rather than asking the human to reconstruct them. When partial, identify only the smallest missing fact. When absent, start with the actual machine hostname/address—not an internal logical profile name.
165
170
 
166
- ```text
167
- Hostname/address: NOT SET
168
- SSH user: deploy
169
- ```
170
-
171
- Ask only for the next unresolved simple fact or authorization needed to repair that state.
171
+ Only after explicit `[REMOTE READ ONLY]` authorization may remote checks occur.
172
172
 
173
- ### No configuration
173
+ When SSH is the approved transport:
174
174
 
175
- Do not ask for a logical target/profile identifier first. Start with the machine:
175
+ - current address is connectivity information, not trusted identity;
176
+ - preserve strict host-key verification;
177
+ - independently verified trust is required;
178
+ - unknown/changed host identity fails closed;
179
+ - never scan the LAN, silently choose another host, disable strict checking, or autoaccept a replacement key.
176
180
 
177
- ```text
178
- STAGING IS NOT CONFIGURED ON THIS PC
181
+ Read-only remote evidence may include OS/version, architecture, identity/groups, runtime state, disk/memory, listening ports, and approved path ownership when relevant.
179
182
 
180
- What hostname or IP address should Staging use?
181
- ```
183
+ #### Route defaults
182
184
 
183
- Then ask one material fact at a time, such as the SSH/deployment user, only when it is not already defined by repository policy or reusable workstation configuration.
185
+ Keep machine hostname/address separate from application route hostname.
184
186
 
185
- Once the human-facing machine facts are known, use repository/Deployment-Kit tooling to create the required internal profile/binding. Prefer deriving/reusing a stable internal identifier from confirmed state when the installed tooling supports it. Surface that identifier only when ambiguity or troubleshooting makes it useful.
187
+ If installed tooling defines deterministic route defaults from stable inputs such as `appSlug + environment`, derive and present those defaults before asking for free-form hostnames. Confirmation does not authorize route registration/Caddy/DNS changes.
186
188
 
187
- ## 4. State-driven progression
189
+ Trusted-LAN `.local` aliases are relevant only when the selected topology/adapter actually uses that convention. Do not present them for workstation, public-VPS, private-VPN, or provider-managed topologies that do not use it.
188
190
 
189
- Normal readiness cadence is:
191
+ ### C. Managed-service placement
190
192
 
191
- ```text
192
- select environment
193
- → rediscover current local state
194
- → show/confirm known simple facts
195
- → verify/reuse access
196
- → repair only missing setup when authorized
197
- → verify target OS/platform/security prerequisites
198
- → verify artifact/registry/data/migration/rollback capability prerequisites
199
- → ENVIRONMENT READY TO DEPLOY
200
- → /deploy <environment>
201
- ```
193
+ Managed service is adapter-specific.
202
194
 
203
- Each invocation resumes from observed evidence. Do not make the human rerun the command with a different mode merely because discovery completed or a prerequisite was repaired.
195
+ Before provider questions or API calls, require repository/catalog evidence for an implemented provider adapter and its credential/readiness contract.
204
196
 
205
- Readiness may perform bounded environment-enablement writes when they are necessary and separately authorized, such as local profile/key/trust setup, target-side access setup, runtime/platform prerequisite setup, data/backup directory preparation, firewall preparation, or registry credential setup. These are readiness/setup operations, not application deployment.
206
-
207
- Application deployment remains owned by `/deploy`.
208
-
209
- ### Read-only status
210
-
211
- `/deployment-readiness status [environment]` is a read-only overview.
212
-
213
- With an environment, summarize that environment's local configuration/readiness state. Without an environment, summarize all configured named deployment environments without remotely probing every machine:
197
+ If no such adapter exists:
214
198
 
215
199
  ```text
216
- Environment Role Local setup Last readiness
217
- Staging non-production CONFIGURED READY TO DEPLOY / STALE / UNKNOWN
218
- Production production PARTIAL NOT READY
219
- ```
200
+ DEPLOYMENT BINDING NOT YET SUPPORTED
220
201
 
221
- Use only evidence that actually exists. `status` does not authorize remote checks or writes.
202
+ Environment: <name>
203
+ Desired placement: managed-service
204
+ Status: CATALOG GAP / PLANNED
222
205
 
223
- ## 5. Select the environment before environment-specific readiness
206
+ No provider credentials requested.
207
+ No provisioning attempted.
208
+ ```
224
209
 
225
- When more than one configured deployment environment exists, select the environment before environment-specific questions or remote checks.
210
+ Do not improvise provider setup from general model knowledge and do not convert this into generic cloud support.
226
211
 
227
- Keep these concepts separate internally even when the human-facing interaction stays simple:
212
+ If a future repository-provided adapter exists, follow that adapter's exact read-only checks, credential boundary, and write gates.
228
213
 
229
- ```text
230
- named environment
231
- → environment role/policy
232
- → configured machine/target binding
233
- → current hostname/address discovery
234
- → independently verified host identity
235
- ```
214
+ ### D. Deferred placement
236
215
 
237
- A non-production Staging target and a Production target may use the same deployment implementation while retaining independent target bindings, data, credentials, readiness evidence, and deployment policy.
216
+ `placement: deferred` / `bindingState: deferred` is intentional state.
238
217
 
239
- Never let one environment silently fall back to another because discovery/access/readiness fails.
218
+ Return a non-error status such as:
240
219
 
241
- ## 6. Session authorization and cadence
242
-
243
- Local read-only discovery is automatic.
220
+ ```text
221
+ DEPLOYMENT INTENTIONALLY DEFERRED
244
222
 
245
- When focused readiness-document updates are useful, present one bounded session choice rather than asking after every answer. Never record secret values.
223
+ Environment: Demo
224
+ Desired outcome: Shareable demo
225
+ Placement: DEFERRED
226
+ Reason: no supported/selected target or provider binding yet
246
227
 
247
- Once a modifying readiness session is authorized:
228
+ Local development, CI, documentation, and learning are not blocked.
248
229
 
249
- ```text
250
- discover existing state
251
- → show/confirm known simple facts
252
- → ask one missing material fact
253
- → record permitted non-secret fact
254
- → explain impact/blocker
255
- → continue from the resulting state
230
+ NEXT WHEN READY
231
+ Choose/configure a supported deployment target or provider adapter, then rerun:
232
+ /deployment-readiness demo
256
233
  ```
257
234
 
258
- Use concise choices for bounded decisions. Ask factual values such as hostname/IP, username, port, OS/version, path, or observed system state as direct free-form/confirmation questions.
235
+ Do not mark workspace readiness failed. Do not provision infrastructure, guess a provider, or ask for secrets merely to make the status green.
259
236
 
260
- ## 7. Verify connectivity and host identity
237
+ ## 3. Shared failure domains / colocated environments
261
238
 
262
- After the human confirms the selected machine, ask or use the explicit choice:
263
-
264
- ```text
265
- Verify connectivity and identity for <environment>? [REMOTE READ ONLY]
266
- ```
239
+ Multiple logical environments may share one physical target or provider failure domain.
267
240
 
268
- Only after authorization may remote inspection occur.
241
+ When repository/target evidence shows that, keep each environment independently targetable and surface:
269
242
 
270
- Prefer repository-provided/Deployment-Kit doctor and verify commands over reconstructing SSH commands by hand.
243
+ ```text
244
+ TOPOLOGY NOTE
271
245
 
272
- When SSH is the approved transport:
246
+ <env-a> and <env-b> are logically isolated but share physical failure
247
+ domain <name>. This can be appropriate for POC cost/learning goals,
248
+ but it does not demonstrate host-level Production isolation.
249
+ ```
273
250
 
274
- - current hostname/IP is an address, not host identity;
275
- - preserve strict host-key verification;
276
- - independently verified host identity/trust is required before readiness;
277
- - an unknown or changed host key fails closed;
278
- - DHCP/mDNS/address changes must not cause trust weakening;
279
- - do not scan the LAN, silently choose another host, disable strict checking, or autoaccept a replacement host key.
251
+ If one environment is Production, its stronger backup/recovery/security/deploy/destructive gates remain fully in force.
280
252
 
281
- Allowed read-only verification may include OS/version, architecture, current identity/groups, approved runtime state, disk/memory, listening ports, and existence/ownership of approved paths when relevant.
253
+ Never infer readiness for one logical environment from another merely because they share hardware.
282
254
 
283
- ## 8. Existing PC, partial setup, and new PC
255
+ ## 4. State-driven cadence
284
256
 
285
- Follow this decision model:
257
+ Normal cadence is:
286
258
 
287
259
  ```text
288
- local discovery
289
- │
290
- ├─ configured + strict verify succeeds
291
- │ → reuse existing access
292
- │ → skip onboarding/setup questions
293
- │
294
- ├─ partial/broken
295
- │ → diagnose exact missing state
296
- │ → repair only that state after the applicable bounded authorization
297
- │ → strict verify again
298
- │
299
- └─ not configured
300
- → ask simple machine facts
301
- → create required local profile/key/agent/trust/binding through approved tooling
302
- → strict verify
260
+ select environment
261
+ → read topology
262
+ → rediscover placement-relevant local state
263
+ → show/confirm already-known facts
264
+ → perform authorized read-only verification
265
+ → repair only missing prerequisites under their exact write gates
266
+ → ENVIRONMENT READY TO DEPLOY
267
+ → /deploy <environment>
303
268
  ```
304
269
 
305
- Possible missing state includes profile/binding, key, SSH-agent membership, independently verified trust, target-side public-key authorization, address discovery, or another repository/tool prerequisite.
270
+ For deferred placement, readiness intentionally stops before the verification/repair stages.
306
271
 
307
- Do not create duplicate credentials merely because another POC uses the same machine. Reuse an already-valid developer-to-machine relationship when the installed tooling and policy allow it.
272
+ For workstation placement, no remote access stage exists.
308
273
 
309
- ## 9. Pre-deploy readiness versus post-deploy validation
274
+ For remote placement, reuse existing access instead of creating duplicate credentials merely because another POC/environment uses the same machine.
310
275
 
311
- Readiness answers: **can `/deploy` safely perform the selected environment's deployment now?**
276
+ ## 5. Read-only status
312
277
 
313
- Before declaring the selected environment ready to deploy, verify only evidence that can exist before the deployment of the selected artifact, such as:
314
-
315
- - selected environment and confirmed machine/target binding;
316
- - strict connectivity/host-identity verification;
317
- - supported developer-workstation launcher;
318
- - expected target OS matches actual target OS;
319
- - shared runtime/platform prerequisites;
320
- - approved release/artifact policy;
321
- - immutable artifact/image digest when applicable;
322
- - artifact/registry accessibility or credential readiness;
323
- - route names validated and collision-free when the installed routing contract supports read-only inventory/plan checks;
324
- - independent environment data/backup paths or the approved ability to create/use them;
325
- - migration capability and prerequisites;
326
- - deployment lock capability;
327
- - rollback/recovery capability and required boundaries;
328
- - production-specific backup/recovery prerequisites when applicable;
329
- - unresolved security blockers = none.
278
+ `/deployment-readiness status [environment]` performs no remote checks or writes.
330
279
 
331
- Do **not** require evidence that can only be produced by deploying the exact selected artifact. On a first deployment, live application route resolution, application health/readiness, smoke results, deployed-release identity, and execution-backed rollback evidence are post-deploy validation, not pre-deploy blockers.
280
+ Without an environment, summarize all known environments with topology-aware columns, for example:
332
281
 
333
- A previously deployed environment may have historical live evidence, but stale evidence for an older artifact does not prove the new artifact's post-deploy behavior.
282
+ ```text
283
+ Environment Role Placement Isolation Exposure Binding Last readiness
284
+ Demo non-production workstation container loopback configured READY / UNKNOWN
285
+ Staging non-production remote-target container public configured STALE / READY
286
+ Production production remote-target container public deferred DEFERRED
287
+ ```
334
288
 
335
- A non-production environment may use a less restrictive artifact policy only when approved requirements say so. Do not infer relaxed Staging behavior.
289
+ Use only evidence that exists. Do not manufacture a target for deferred rows.
336
290
 
337
- ## 10. Bounded setup/provisioning writes
291
+ ## 6. Bounded setup/provisioning writes
338
292
 
339
293
  A missing prerequisite is not authorization to change it.
340
294
 
341
- Examples of bounded readiness actions include:
295
+ Possible readiness writes include:
342
296
 
343
297
  ```text
344
298
  Create/update local environment binding [LOCAL CONFIG WRITE]
@@ -346,55 +300,74 @@ Create local deployment key [LOCAL KEY WRITE]
346
300
  Add key to SSH agent [SSH AGENT WRITE]
347
301
  Enroll independently verified host trust [LOCAL TRUST WRITE]
348
302
  Authorize public key on target [SECURITY / REMOTE WRITE]
349
- Install/upgrade runtime [REMOTE WRITE]
303
+ Install/upgrade runtime/platform [REMOTE WRITE]
350
304
  Create data/backup directories [REMOTE WRITE]
351
305
  Configure firewall [SECURITY / REMOTE WRITE]
352
306
  Configure registry credential [SECRET / REMOTE WRITE]
353
307
  Set source-hosting environment variable/secret [SOURCE-HOSTING WRITE]
354
308
  ```
355
309
 
356
- Use the installed repository/tool's exact authorization phrase when it defines one. Do not weaken or replace that contract with a generic label.
310
+ Use repository/tool exact authorization phrases when defined.
311
+
312
+ Do not hide application deployment inside readiness. In particular, readiness must not start/replace the application runtime, register the final application route, migrate the selected release, or perform release-specific smoke validation. Those belong to `/deploy`.
313
+
314
+ ## 7. Pre-deploy versus post-deploy evidence
315
+
316
+ Readiness answers: **can `/deploy` safely perform the selected environment's deployment now?**
317
+
318
+ Verify only evidence that can exist before deploying the selected artifact.
319
+
320
+ Across placements this may include:
321
+
322
+ - selected logical environment/role/topology;
323
+ - adapter implementation availability;
324
+ - exact target/provider binding when required;
325
+ - local Docker or strict remote identity/access depending on placement;
326
+ - expected target OS/runtime where applicable;
327
+ - artifact policy and immutable artifact identity;
328
+ - registry/artifact accessibility;
329
+ - route/port ownership availability;
330
+ - data/backup/migration prerequisites;
331
+ - deployment lock/recovery capability;
332
+ - Production-specific backup/recovery/security prerequisites;
333
+ - unresolved security blockers = none.
334
+
335
+ Do not require first-deployment live route, application health, smoke, deployed-release identity, or execution-backed rollback evidence before deployment. Those are post-deploy validation.
336
+
337
+ ## 8. Production policy
338
+
339
+ Production is logical policy, not hardware count.
340
+
341
+ A Production environment may be on a dedicated host, a shared VPS, or another supported placement. None of those choices weakens Production authorization.
342
+
343
+ Readiness must include project-required Production backup/recovery/security evidence and explicitly report any shared physical failure domain.
357
344
 
358
- Do not register the application route, deploy the application container/process, migrate the selected release, or run release-specific live smoke validation as a hidden readiness side effect. Those belong to `/deploy` when the repository deployment contract includes them.
345
+ Readiness itself never authorizes Production deployment.
359
346
 
360
- ## 11. Readiness handoff
347
+ ## 9. Final handoff
361
348
 
362
- For any selected environment that has satisfied its pre-deploy requirements:
349
+ When pre-deploy requirements are satisfied, report the topology and only placement-relevant evidence:
363
350
 
364
351
  ```text
365
352
  ENVIRONMENT READY TO DEPLOY
366
353
 
367
354
  Environment: <name>
368
355
  Role: <role>
369
- Hostname/address: <confirmed non-secret value when appropriate>
370
- Target OS/architecture: <verified>
371
- Access/host identity: VERIFIED
356
+ Purpose: <purpose when known>
357
+ Placement: <workstation|remote-target|managed-service>
358
+ Isolation: <...>
359
+ Exposure: <...>
360
+ Binding: VERIFIED / LOCAL / provider-specific
361
+ Access/identity: VERIFIED / NOT APPLICABLE
372
362
  Platform prerequisites: READY
373
- Route identity/plan: VALID / AVAILABLE when applicable
374
- Release/artifact: <verified immutable identity when required>
375
- Registry/artifact access: READY when applicable
376
- Persistence/migration capability: READY
377
- Rollback/recovery capability: READY
363
+ Artifact: <verified immutable identity when required>
364
+ Persistence/recovery prerequisites: READY / NOT APPLICABLE
378
365
  Security blockers: NONE
379
366
 
380
367
  POST-DEPLOY VALIDATION PENDING
381
- Live route/health/smoke/release-specific rollback evidence is established by /deploy.
382
368
 
383
369
  NEXT
384
370
  /deploy <environment>
385
371
  ```
386
372
 
387
- For a production-role environment, include the additional production policy/backup/recovery evidence required by the project, but do not change the readiness mechanism or command name.
388
-
389
- This is pre-deploy readiness evidence, not deployment authorization. `/deploy` owns the actual deployment write gate for the exact environment, verified target, artifact, and current evidence.
390
-
391
- ## 12. Post-readiness
392
-
393
- Once an environment is ready to deploy:
394
-
395
- - record non-secret readiness evidence in the repository-approved place when useful;
396
- - keep readiness independent from other environments;
397
- - use `/deploy <environment>` for the application deployment and release-specific live validation;
398
- - return to `/deployment-readiness <environment>` when machine binding, address, expected OS/runtime, security posture, credentials, registry access, data prerequisites, or another material pre-deploy prerequisite changes.
399
-
400
- Application rollback execution, database restore/destructive recovery, and environment tear-down remain separately governed when data safety warrants it.
373
+ This is evidence, not deployment authorization. `/deploy` owns the actual deployment write gate for the exact environment, placement, target/provider, artifact, and current evidence.