Now I have everything I need to produce the ADR.

Shipwright is a bash-based CLI tool with 100+ commands dispatched through a central router (scripts/sw) via a case statement. Each command is a standalone bash script (scripts/sw-<name>.sh) with a paired test file (scripts/sw-<name>-test.sh). The sw-hello.sh command (67 lines) is the established template for simple diagnostic/utility commands and is the direct model for this implementation.

The ping command serves a concrete operational purpose: it provides the simplest possible liveness probe. shipwright ping can be called by health-check scripts, CI pipelines, and orchestration layers to verify the CLI binary is installed and executable without invoking any external dependencies (GitHub API, tmux, database, etc.).

Constraints from the codebase:

• All scripts must be Bash 3.2 compatible — no declare -A, no ${var,,}, no readarray
• set -euo pipefail is mandatory in every script
• Output must be plain echo to stdout; no ANSI color in the primary response payload (color helpers are for diagnostics, not protocol output)
• The router dispatches via exec — the case entry must be placed before the *) default at scripts/sw:608
• Test suites must be registered in the npm test chain in package.json

Standalone script pattern, structurally identical to sw-hello.sh.

The command is implemented as scripts/sw-ping.sh with:

• echo "pong" as the sole output on the happy path (no color wrappers — the response is a protocol token, not a user message)
• exit 0 (implicit from echo succeeding under set -euo pipefail)
• --help/-h and --version/-v flags (consistent with every other command; omitting them would make ping the only command that doesn't respond to --help)
• Unknown-argument guard with exit 1

The router entry is inserted at scripts/sw:607 (after hello), before *)):

ping)
 exec "$SCRIPT_DIR/sw-ping.sh" "$@"
 ;;

┌─────────────────────────────────────────────────────────────────┐
│ shipwright CLI │
│ │
│ User / CI / Health-check script │
│ │ │
│ ▼ │
│ ┌──────────────┐ exec ┌─────────────────────────────┐ │
│ │ scripts/sw │──────────▶│ scripts/sw-ping.sh │ │
│ │ (router) │ │ ┌───────────────────────┐ │ │
│ │ │ │ │ arg parser (case) │ │ │
│ │ case "ping" │ │ │ - "" → echo "pong" │ │ │
│ │ │ │ │ - --help/-h → help │ │ │
│ └──────────────┘ │ │ - --version/-v → ver │ │ │
│ │ │ - * → error + exit 1 │ │ │
│ ┌──────────────────────┐ │ └───────────────────────┘ │ │
│ │ scripts/sw-ping- │ │ │ │
│ │ test.sh │ │ Deps: lib/helpers.sh │ │
│ │ (6 test cases) │ │ (optional, fallback inline) │ │
│ └──────────────────────┘ └─────────────────────────────┘ │
│ ▲さんかく │
│ npm test chain (package.json) │
└─────────────────────────────────────────────────────────────────┘

Component responsibilities — one reason to change each:

# ── sw-ping.sh public interface ─────────────────────────────────────────────
# Invocation forms:
# sw-ping.sh → stdout: "pong\n" exit: 0
# sw-ping.sh --help → stdout: <help text> exit: 0
# sw-ping.sh -h → stdout: <help text> exit: 0
# sw-ping.sh --version → stdout: "<semver>\n" exit: 0
# sw-ping.sh -v → stdout: "<semver>\n" exit: 0
# sw-ping.sh <unknown> → stderr: error msg exit: 1
# Preconditions:
# - bash >= 3.2 available at /usr/bin/env bash
# - lib/helpers.sh may or may not be present (graceful fallback required)
# Postconditions (happy path):
# - Exactly the string "pong" followed by a newline written to stdout
# - Nothing written to stderr
# - Exit status 0
# Error contract:
# - Exit status 1 on unrecognized argument
# - Error message to stderr (not stdout)
# - No side effects (no files written, no network calls, no env mutations)
# ── Router contract (scripts/sw lines 605-613) ──────────────────────────────
# Input: 1ドル == "ping"
# Effect: exec replaces the router process with sw-ping.sh
# All remaining argv ($@) forwarded to sw-ping.sh
# No return: exec never returns on success

stdin ──(not read)──▶ sw-ping.sh
argv ──────────────▶ arg parser (case statement)
 │
 ┌──────────┴──────────┐
 │ "" (no args) │ --help/-h │ --version/-v │ *
 ▼ ▼ ▼ ▼
 echo "pong" cat <<EOF echo $VERSION error() >&2
 to stdout to stdout to stdout + show_help
 exit 0 exit 0 exit 0 exit 1

There is no state read or written. No files. No environment variables queried beyond BASH_SOURCE (for SCRIPT_DIR). No network. This is a pure function: deterministic, zero side effects, zero external dependencies.

1. Inline in router (scripts/sw) — Pros: zero new files. Cons: violates every established convention; untestable in isolation; sets a precedent that degrades the architecture for every future simple command; inconsistent with hello, which is structurally identical in complexity. Rejected.

2. Shared "simple command" library — Pros: DRY across hello and ping. Cons: premature abstraction — two commands don't justify a shared library; adds indirection with no benefit; forces future commands into a rigid template. Rejected.

3. printf instead of echo — Pros: more portable across edge-case /bin/sh interpreters. Cons: the entire codebase uses echo; this file is #!/usr/bin/env bash so portability is not a concern; printf with no format string is unconventional. Rejected — use echo "pong".

Files to create:

Files to modify:

Dependencies: None. No new packages, libraries, or external tools.

Risk areas:

Error non-propagation by design: sw-ping.sh has no network calls, no file I/O, no subprocess spawning. The only possible failures are (a) broken stdout (environment issue, not command bug) or (b) unexpected argv (user error). Both terminate immediately with a non-zero exit. There is no retry logic, no partial state, and no cleanup required.

• bash scripts/sw-ping.sh outputs exactly pong (one line, no trailing spaces, no ANSI codes) and exits 0
• bash scripts/sw-ping.sh --help outputs text containing USAGE and exits 0
• bash scripts/sw-ping.sh -h same as --help
• bash scripts/sw-ping.sh --version outputs a string matching ^[0-9]+\.[0-9]+\.[0-9]+ and exits 0
• bash scripts/sw-ping.sh --invalid exits 1 and writes to stderr (not stdout)
• bash scripts/sw-ping-test.sh reports PASS: 6 FAIL: 0 and exits 0
• bash scripts/sw ping outputs pong and exits 0 (router integration)
• npm test exits 0 with all suites passing (regression gate)
• No new files other than sw-ping.sh and sw-ping-test.sh are created
• VERSION in sw-ping.sh matches package.json "version" field (currently 3.2.4)