Skill: harden decision gates and port conflict detection

- Elevate deployment mode (rootless/rootful) and volume strategy to
  required planning items and hard-stop bullets
- Add host port conflict detection for PublishPort= in planning,
  hard stops, compose-mapping, and validation checklist
- Add execution-phase confirmation gate before writing files
- Add degradation rule for unavailable structured input tools

SKILL.md

@@ -51,7 +51,12 @@ In planning:
 4. Identify unresolved deployment decisions and ask the user about them.
 5. Summarize what you learned and state the proposed reviewable output location before moving on.
 
-Planning is where you must ask about unresolved high-impact values such as domains, host paths, credentials, storage choices, optional services, deployment mode, and output-location conflicts.
+Planning is where you must ask about unresolved high-impact values. The following must be explicitly confirmed before leaving planning:
+
+- **Deployment mode** (rootless vs rootful) — determines Quadlet target directory, systemctl scope, linger requirement, and helper-script behavior.
+- **Volume strategy** (named volume vs bind mount vs `.volume` unit) — determines whether `.volume` files are generated and how mount paths are written.
+- Domains, host paths, credentials, optional services, and output-location conflicts.
+- **Host port availability** — when `PublishPort=` is used, detect whether the host-side port is already occupied before proceeding.
 
 If the source has many env variables, reduce them to a small decision list instead of dumping raw templates back to the user.
 
@@ -76,6 +81,8 @@ Do not start execution until the user has reviewed and confirmed the finalize sn
 
 Goal: write the approved artifacts.
 
+Before writing any file, confirm that the user has explicitly approved the finalize snapshot. If the finalize phase was skipped or the user has not confirmed, stop and ask.
+
 In execution:
 
 1. Generate the approved Quadlet files.
@@ -98,10 +105,15 @@ Stop and ask the user before finalizing or generating runnable output when any o
 - required support files or directories referenced by mounts, docs, commands, or scripts
 - required env values for minimal startup
 - likely env-key typos or mismatches
+- host port conflicts when `PublishPort=` is used — detect occupied host ports before finalizing
+- unresolved deployment mode (rootless vs rootful)
+- unresolved volume strategy (named volume vs bind mount vs `.volume` unit)
 - a mismatch between deployment mode and the intended operator model or file locations
 
 Do not keep moving forward by guessing through these gaps.
 
+If a structured input tool is unavailable, ask the user directly in conversation before proceeding. Do not substitute defaults for unresolved high-impact decisions.
+
 ## Decision Priority
 
 When rules or signals conflict, use this priority order:

references/compose-mapping.md

@@ -51,6 +51,7 @@ Use this file when converting `docker-compose.yml` or `compose.yaml` into Quadle
 
 - For a standalone service, map to `PublishPort=` on the `.container`.
 - For a pod-based topology, prefer `PublishPort=` on the `.pod` when the published ports belong to the pod boundary rather than one child container.
+- When `PublishPort=` maps a host-side port, detect whether that host port is already in use before finalizing the mapping. Check for TCP/UDP listeners on the host using an available port-detection method. If a conflict is found, stop and ask the user whether to change the host port, skip the mapping, or resolve the conflict manually. Do not silently remap occupied host ports to an alternative.
 
 ### `volumes`
 

references/validation.md

@@ -97,6 +97,7 @@ Runnable-output gate checklist template:
 - [ ] 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
+- [ ] host-side `PublishPort=` ports are free on the target host
 
 Do not call the result runnable until every item above is checked.
 
@@ -113,6 +114,7 @@ Do not call the result runnable until every item above is checked.
 - required repo-local config, init assets, or helper scripts missing from the installed artifact set
 - permissions on rootless bind mounts
 - readiness assumptions hidden behind `depends_on`
+- host port already in use by another service or process, causing `PublishPort=` binding to fail at start
 
 ## Troubleshooting Posture