# Host OS Portability

This is a Post.Build.Ship reference, not a standalone skill.

Use this reference when `post`, `build`, or `ship` is already active and the approved task changes
code, tests, snapshots, package tooling, scripts, or CI whose observed behavior or assertions depend
on the operating system of the developer or CI machine.

Do not use this reference for every cross-platform app change. Cross-platform runtime surface
portability and developer-host portability are different axes:

1. **runtime surface portability** covers web, desktop, mobile, and shared app code running in the
   target product surfaces.
2. **host OS portability** covers macOS, Linux, and Windows machines running tests, scripts, package
   tooling, code generation, local development commands, and CI.

This reference supplements Post.Build.Ship. It preserves Authorizing User authority, observable
acceptance, host boundaries, fail-fast approvals, proportionate QA, ownership, and Ship safety. It
adds no mandatory review or presentation fields.

## Trigger Scope

Apply this reference only when the change, its tests, or its QA evidence depends on host OS details
such as:

1. path separators, absolute path formats, drive letters, home directory expansion, or path strings
   observed in outputs, errors, logs, snapshots, or assertions
2. `chmod`, mode bits, executable flags, shebang execution, or package binaries that rely on POSIX
   permissions
3. symlinks, hard links, junctions, case sensitivity, case-only renames, or filesystem watcher
   behavior
4. temp-directory layout, cache paths, lockfile paths, or generated file locations that differ by
   host OS
5. shell selection and environment variables such as `SHELL`, `COMSPEC`, `cmd.exe`, `PATH`,
   `PATHEXT`, `HOME`, `USERPROFILE`, or `TMPDIR`
6. spawned-process `argv`, quoting, escaping, glob expansion, package-script shell syntax, shell
   operators, or command substitution
7. CRLF/LF handling, snapshots with platform-specific line endings, `.gitattributes`, git `autocrlf`,
   or EOL normalization

When none of these host-observed concerns are involved, keep the normal Post.Build.Ship workflow and
do not add host-portability ceremony.

## Guidance

Prefer comparing structured values over raw host-formatted strings. Normalize paths with the
language or runtime path APIs before asserting, and avoid expecting one separator style in test
fixtures unless the fixture is intentionally platform-specific.

For process execution, avoid shell-specific syntax when a direct executable plus explicit `argv` is
available. If shell behavior is the feature under test, name the shell contract explicitly and cover
Windows behavior such as `COMSPEC` or `cmd.exe` separately from POSIX `SHELL` behavior.

For executable files and generated bins, verify whether the repository relies on mode bits or
`chmod`. Windows may not preserve or enforce POSIX executable flags the same way macOS and Linux do,
so tests should assert the portable contract rather than a Unix-only implementation detail unless
that detail is intentionally in scope.

For symlinks and case sensitivity, do not assume the local filesystem matches CI or another
developer's machine. Prefer APIs and tests that tolerate platform differences, or record the
platform-specific precondition explicitly when the behavior cannot be portable.

For line endings, keep text fixtures and snapshots deterministic. Use `.gitattributes` or explicit
normalization when CRLF/LF matters, and avoid snapshot churn caused only by host checkout settings.
When testing EOL behavior itself, include the intended CRLF/LF cases as explicit data instead of
depending on the current checkout mode.

## Post Planning Cross-Check

When the trigger applies, `post` should capture the host-sensitive decision inside existing handoff
fields: scope, acceptance criteria, exact QA commands, known risks, and fallback approvals. Do not add
new mandatory handoff fields for host portability.

Planning should answer:

1. which host OS details are observable in the change
2. whether assertions need normalization, explicit platform branches, or platform-specific fixtures
3. which host environments the available QA actually exercises
4. whether documentation should call out an intentional host limitation

## Build Cross-Check

When implementing, keep the diff portable by default:

1. avoid hard-coded `/` or `\` in observed path outputs unless the output contract requires it
2. avoid POSIX-only package-script syntax unless the package is intentionally POSIX-only and the
   handoff records that limitation
3. keep CRLF/LF-sensitive fixtures explicit and deterministic
4. avoid changing broad `.gitattributes`, snapshot, or generated-output policy unless it is in scope
5. rerun the exact QA commands listed in the handoff and record what host OS they ran on when it
   affects interpretation

## Ship Cross-Check

`ship` treats this reference as a read-only cross-check against the existing handoff and staged diff,
like page-addition and starter-kit references. It does not require new mirrored handoff fields.

Before authoritative final QA, check that the completed diff does not accidentally encode the current host OS into
tests, snapshots, scripts, or docs. If the handoff says a host-specific limitation is intentional,
verify the staged diff documents or tests that limitation clearly enough for future macOS, Linux, and
Windows contributors.

## Evidence

Commit `019ec550d` is evidence for this reference: tests and tooling can lag production portability
even when production code already handles Windows correctly. Treat host portability as its own review
axis when the test or tooling surface observes OS details.

## Link And Citation QA

`intent validate` validates skill files, but it does not validate reference citations or links inside
references. When editing this reference or adding citations to it, explicitly verify:

1. `skills/post-build-ship/references/host-portability.md` exists
2. every workflow skill that cites this reference uses the correct relative path text
3. required evidence citations such as `019ec550d` remain present
4. any relative Markdown link added in this reference resolves to a real file