Refine finalize review and output prompting rules.

Align the Quadlet migrator skill with a conversation-based finalize flow, default current-directory output, and opt-in AutoUpdate planning only when fully-qualified registry images support it.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

references/deployment-notes.md

@@ -4,11 +4,18 @@ Use this file when the user wants deployment-ready instructions alongside genera
 
 ## Delivery flow
 
-1. Generate the reviewable artifacts in the current working directory.
-2. Review the generated Quadlet files, env files, helper scripts, and any required repo-local support files or directories.
-3. Use `install.sh` to copy only the reviewed Quadlet unit files into the chosen Quadlet directory.
-4. Use `reload.sh`, `start.sh`, `stop.sh`, and `restart.sh` to manage the deployed services.
-5. Use `uninstall.sh` when the user wants to remove the installed reviewed Quadlet unit files without broad Podman cleanup.
+For `design` mode, stop after the user reviews the finalize snapshot in conversation.
+For `generate` mode, continue only after the user has reviewed and confirmed the finalize snapshot or requested edits.
+
+1. Generate the reviewable artifacts in the current working directory by default, or in another user-requested output directory.
+2. Resolve high-impact planning questions with the user before freezing the design.
+3. Review the finalized design snapshot together with the generated Quadlet files, env files, helper scripts, and any required repo-local support files or directories.
+4. Use `install.sh` to copy only the reviewed Quadlet unit files into the chosen Quadlet directory.
+5. Run the appropriate `daemon-reload` command.
+6. Use `start.sh`, `stop.sh`, and `restart.sh` to manage the deployed services.
+7. Use `uninstall.sh` when the user wants to remove the installed reviewed Quadlet unit files without broad Podman cleanup.
+
+Do not start execution until the user has reviewed and confirmed the finalize snapshot or requested edits.
 
 ## Apply target directory
 
@@ -28,16 +35,14 @@ See `podman-systemd.unit.5.md` for the full search-path matrix.
 
 - `install.sh`: canonical apply script; copy only reviewed Quadlet unit files into the selected Quadlet target directory
 - do not generate a separate `apply.sh` by default; reserve that alternate name only when the user explicitly asks for it
-- `uninstall.sh`: remove the installed reviewed Quadlet unit files from the selected Quadlet target directory, stopping affected services first when needed
-- `reload.sh`: run the appropriate `daemon-reload` command after installation changes
-- `start.sh`: start the generated units; when the topology uses a `.pod`, start the pod's systemd service derived from `ServiceName=` when present on the `.pod`, otherwise use Quadlet's default generated pod service name, instead of also starting each child container service individually
-- `stop.sh`: stop the generated units; when the topology uses a `.pod`, stop the pod's systemd service derived from `ServiceName=` when present on the `.pod`, otherwise use Quadlet's default generated pod service name, instead of duplicating per-container stop commands for its child containers
-- `restart.sh`: restart the generated units after reload or config changes; when the topology uses a `.pod`, restart the pod's systemd service derived from `ServiceName=` when present on the `.pod`, otherwise use Quadlet's default generated pod service name, instead of also restarting each child container service individually
+- `install.sh` must not start, stop, restart, or reload services as a side effect
+- `uninstall.sh`: remove the installed reviewed Quadlet unit files from the selected Quadlet target directory
+- `uninstall.sh` should stop affected services before removing their installed unit files, and should not delete support files from the current-directory deliverable set, unrelated files, shared directories, named volumes, images, or Podman objects unless the user explicitly asks for broader cleanup
+- `reload.sh`: run only the appropriate `daemon-reload` command after installation changes
+- `start.sh`, `stop.sh`, `restart.sh`: manage services only and must not silently install or overwrite reviewed files
+- when a generated topology includes `<name>.pod` plus child containers linked with `Pod=<name>.pod`, helper scripts should use the pod service as the lifecycle entrypoint; derive that service name from `ServiceName=` when present on the `.pod`, otherwise use Quadlet's default generated pod service name, instead of duplicating per-container lifecycle commands for child units
 
 Keep installation separate from service-management scripts so the user can review generated files before applying them.
-`install.sh` should copy reviewed Quadlet unit files into the chosen Quadlet target directory only, and should not start, stop, restart, or reload services as a side effect.
-`uninstall.sh` should remove only the installed reviewed Quadlet unit files, stop affected services before removal when needed, and leave the support files in the current-directory deliverable set, unrelated files, shared directories, named volumes, images, and Podman objects alone unless the user explicitly asks for broader cleanup.
-`reload.sh`, `start.sh`, `stop.sh`, and `restart.sh` should not silently install or overwrite reviewed files.
 Do not use `ServiceName=` as an application connection target. It controls the generated systemd unit name only. When services communicate over a shared network outside a single pod namespace, prefer container names, pod names, or explicit `NetworkAlias=` values.
 Within a single pod, use `127.0.0.1` / `localhost` for container-to-container communication instead of generating `AddHost=` entries whose purpose is sibling-container discovery.
 If a service inside the pod must accept connections from sibling containers, ensure its effective listen address is reachable within the shared pod namespace, typically `127.0.0.1` or `0.0.0.0`. When the upstream service exposes this through environment variables or similar runtime configuration, preserve or generate that setting explicitly.
@@ -57,11 +62,12 @@ Execution checklist template before install:
 
 - [ ] all reviewed artifacts are present in the current-directory deliverable tree
 - [ ] required support files and directories are included alongside the Quadlet and env artifacts
-- [ ] unit files map to the intended Quadlet directory
+- [ ] every `EnvironmentFile=` path resolves to an actual reviewed file
 - [ ] support files remain in the current-directory deliverable tree at the absolute paths referenced by mounts and scripts
-- [ ] startup-critical env keys are present in the final env sources
+- [ ] startup-critical env keys are present, or explicitly marked as unresolved placeholders
 - [ ] any unresolved values are clearly marked as intentionally non-runnable placeholders
-- [ ] service-management scripts operate on the same reviewed artifact set that will be installed
+- [ ] service-management scripts operate on the same reviewed artifact set that finalize approved
+- [ ] runnable-output gate passed before describing the result as runnable
 
 ## Rootless operational notes
 
@@ -95,7 +101,7 @@ Use the timeout especially when first start may need to pull large images or bui
 
 ## Useful optional enhancements
 
-- `AutoUpdate=registry` for opt-in automatic image refresh workflows
+- `AutoUpdate=registry` for opt-in automatic image refresh workflows when the approved image strategy uses fully qualified registry images
 - explicit `.volume` or `.network` units when the user wants declarative infrastructure instead of implicit Podman objects
 
 ## Output language

references/validation.md

@@ -4,11 +4,12 @@ Use this file when the user asks how to verify or troubleshoot generated Quadlet
 
 ## Basic deployment flow
 
-1. Review the generated files in the current working directory and confirm the expected Quadlet units, env files, helper scripts, and required repo-local support files exist.
-2. Run `install.sh` to copy only the reviewed Quadlet unit files into the target Quadlet directory.
-3. Run the appropriate reload command.
-4. Start the relevant units and inspect their status.
-5. If needed, run `uninstall.sh` to remove the installed reviewed artifact set before regenerating or abandoning the deployment.
+1. Review the generated files in the current working directory by default, or in another user-requested output directory, and confirm the expected Quadlet units, env files, helper scripts, and required repo-local support files exist.
+2. Confirm the user has already reviewed the finalize snapshot and approved execution, or requested edits that were incorporated before writing runnable artifacts.
+3. Run `install.sh` to copy only the reviewed Quadlet unit files into the target Quadlet directory.
+4. Run the appropriate reload command.
+5. Start the relevant units and inspect their status.
+6. If needed, run `uninstall.sh` to remove the installed reviewed artifact set before regenerating or abandoning the deployment.
 
 If the user requested an alternate apply script name explicitly, substitute that name where needed, but treat `install.sh` as the default documentation path.
 
@@ -59,20 +60,25 @@ systemd-analyze --user verify <unit>.service
 Before calling the result runnable, verify that:
 
 - every referenced `EnvironmentFile=` exists at the path referenced by the installed unit
-- required env keys are actually present in the final env sources
+- required env keys are actually present in the final env sources, or are explicitly surfaced as unresolved placeholders
 - bind-mounted files and directories exist at the absolute paths referenced by the generated Quadlet files
 - bind-mounted file-versus-directory shape still matches the source input
+- if `AutoUpdate=registry` is enabled, the generated unit uses a fully qualified image reference
 - when sibling containers in the same pod must connect to a service, its effective listen address is reachable within the pod namespace (`127.0.0.1` or `0.0.0.0`, unless upstream docs require another reachable bind address)
 - repo-local entrypoint or helper scripts referenced by the container exist and are executable when needed
 - initialization assets such as `init.sql`, seeds, bootstrap files, or config templates are present where the deployment expects them
+- service-management scripts operate on the same reviewed artifact set that finalize approved
 
 Runnable-output gate checklist template:
 
 - [ ] the support-file set is complete
+- [ ] every `EnvironmentFile=` path resolves to an actual reviewed file
 - [ ] env completeness check passed against the actual final env sources
+- [ ] startup-critical env keys are present, or explicitly marked as unresolved placeholders
 - [ ] unit files are installed in the intended Quadlet directory
 - [ ] support files remain available at the absolute paths expected by mounts and scripts
 - [ ] bind-mounted file-versus-directory shape still matches the source input
+- [ ] if `AutoUpdate=registry` is enabled, the generated unit uses a fully qualified image reference
 - [ ] intra-pod service listeners that must accept sibling-container traffic are reachable on `127.0.0.1` or `0.0.0.0`, unless upstream docs require another reviewed bind address
 - [ ] service-management scripts operate on the same artifact set that was reviewed
 - [ ] no required support file, env key, or typo-suspect mismatch remains unresolved
@@ -82,6 +88,7 @@ Do not call the result runnable until every item above is checked.
 ## Common failure causes
 
 - unsupported Quadlet option for the installed Podman version
+- `AutoUpdate=registry` was enabled but the image reference is not fully qualified
 - bind-mount source directory missing
 - files were generated but `install.sh` has not yet copied the unit files into the target rootless or rootful unit directory
 - wrong rootless or rootful apply target directory