diff --git a/SKILL.md b/SKILL.md index 3eaf8d9..54b3178 100644 --- a/SKILL.md +++ b/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: diff --git a/references/compose-mapping.md b/references/compose-mapping.md index d4a01b2..8bc4553 100644 --- a/references/compose-mapping.md +++ b/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` diff --git a/references/validation.md b/references/validation.md index 961cc70..720dc3a 100644 --- a/references/validation.md +++ b/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