coding-os 0.3.2__py3-none-any.whl

core/skills/security-web/references/supply-chain.md

@@ -0,0 +1,179 @@
+# Supply-Chain Hardening
+
+The most common vector in the 2024-2025 breach landscape. Defense is a layered process, not a single tool.
+
+## The Threat Surface
+
+A modern app pulls hundreds of transitive dependencies. Each one is a potential vector:
+
+1. **Typosquatting** — `requests` vs `requets`, `lodash` vs `lodash-es-utils`. Devs mistype, install malware.
+2. **Compromised maintainer account** — original maintainer's npm/PyPI account hijacked, malicious version published. (Examples: `event-stream` 2018, `colors.js` 2022, `xz-utils` 2024.)
+3. **Dependency confusion** — internal package name registered on public registry by attacker; pip/npm prefers public version.
+4. **Source-code injection** — malicious PR merged into legitimate package.
+5. **Build-time compromise** — CI pipeline tokens leaked → attacker publishes a tainted release.
+
+## Defenses — The Layered Approach
+
+### Layer 1: Lockfiles (mandatory)
+
+Every package manager produces a lockfile that pins exact transitive versions + integrity hashes:
+
+| Ecosystem | Lockfile |
+|---|---|
+| Go | `go.sum` |
+| Python (uv) | `uv.lock` |
+| Python (poetry) | `poetry.lock` |
+| Python (pip-tools) | `requirements.txt` (compiled, with hashes) |
+| Node (npm) | `package-lock.json` |
+| Node (yarn) | `yarn.lock` |
+| Node (pnpm) | `pnpm-lock.yaml` |
+
+Rules:
+
+- **Commit the lockfile**.
+- **CI uses `--frozen-lockfile`** (or equivalent: `npm ci`, `yarn install --immutable`, `pnpm install --frozen-lockfile`, `uv sync --frozen`). Fails if `package.json` and lockfile disagree.
+- **Hash verification on install** — every package manager does this when given a lockfile with hashes.
+
+### Layer 2: Vulnerability Scanning (CI)
+
+Run on every PR. Fail on high-severity. Don't merge until resolved (or explicitly waived with an expiration).
+
+```yaml
+# .github/workflows/audit.yml
+jobs:
+  audit:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      # Go
+      - run: go install golang.org/x/vuln/cmd/govulncheck@latest
+      - run: govulncheck ./...
+
+      # Python
+      - run: pipx install pip-audit
+      - run: pip-audit --strict
+
+      # Node (RN client)
+      - run: cd mobile && yarn install --immutable
+      - run: cd mobile && yarn npm audit --severity high --recursive
+
+      # Cross-ecosystem (preferred — single tool, full coverage)
+      - run: pipx install osv-scanner
+      - run: osv-scanner --recursive .
+```
+
+OSV (Open Source Vulnerabilities) database aggregates across ecosystems. Use it as the canonical scanner.
+
+### Layer 3: Dependency Review on PRs
+
+- **GitHub Dependency Review** (built-in) — flags new vulnerabilities introduced by the PR.
+- **Dependabot / Renovate** — automated PRs to update deps. Review like any other PR (don't auto-merge transitives blindly; let security patches auto-merge with full test pass).
+
+### Layer 4: Minimize Surface
+
+- **Audit every new dependency** at PR time. One paragraph in the PR description: what does this do? Is there a smaller alternative? Could you write it yourself in <100 lines?
+- **Remove unused deps** quarterly: `depcheck` (Node), `pip-autoremove` (Python), `go mod tidy` (Go).
+- **Avoid abandoned packages**: check last-commit timestamp; replace anything inactive >2 years.
+- **Pin major versions** in `package.json` / `pyproject.toml` (`^` is fine for minor/patch with lockfile; never `latest`).
+
+### Layer 5: Dependency Confusion Defense
+
+For internal packages (private monorepo, internal SDK):
+
+- **Scoped packages** in npm: `@app/internal-utils` — register the scope on npmjs.org even if you never publish, claiming it.
+- **Private registry first** in `.npmrc`:
+  ```
+  registry=https://registry.npmjs.org
+  @app:registry=https://npm.internal.app.com
+  ```
+- **Python**: Pin internal packages with `extra-index-url` strict ordering, OR install from URL/path directly.
+- **Verify package source** in your build: assert that `@app/internal-utils` resolves from your private registry, not public.
+
+### Layer 6: Provenance + Sigstore
+
+For packages you PUBLISH (your own libraries, internal SDKs):
+
+- **npm provenance** (`--provenance` flag on publish) — attaches verifiable build metadata via Sigstore.
+- **Sigstore** for Go modules and container images.
+- **Reproducible builds** where feasible.
+
+For packages you CONSUME, look for and prefer those with provenance attestations (npm + GitHub now show this on the package page).
+
+### Layer 7: Build Pipeline Hardening
+
+- **Short-lived OIDC tokens** for cloud auth in CI (no long-lived secrets in GitHub Actions / GitLab CI).
+- **Pin GitHub Action versions to commit SHA**, not tag (`uses: actions/checkout@8e5e7e5...` not `@v4`).
+- **Restrict who can approve releases**.
+- **Two-person rule** for publishing high-impact packages.
+- **Separate publish-only credentials** (no PR-merge perms).
+- **Scan the build environment** itself: minimal base images, no unnecessary tools.
+
+### Layer 8: Runtime Detection
+
+You can't catch every bad dep at install. Some defenses run at runtime:
+
+- **Outbound-traffic allowlist** at the network layer (your prod app should only talk to known endpoints). Sudden new outbound destination = exfiltration alert.
+- **Process-level monitoring** (Falco, Tracee) — alerts on `curl | sh` patterns, unusual syscalls.
+- **Container image scanning** (Trivy, Grype) on every build.
+
+## The Build Manifest — SBOM
+
+Generate a Software Bill of Materials per build artifact. Standard format: CycloneDX or SPDX.
+
+```bash
+# Cross-language
+syft scan ./mobile -o cyclonedx-json > sbom-mobile.json
+syft scan ./backend -o cyclonedx-json > sbom-backend.json
+
+# Then verify SBOM doesn't have known vulns:
+grype sbom:sbom-mobile.json
+```
+
+Attach SBOMs to GitHub releases. Customers / auditors / compliance teams will ask.
+
+## Operational Practices
+
+### Weekly Dependency Hygiene
+
+- [ ] `osv-scanner --recursive .` — zero high-severity.
+- [ ] Dependabot / Renovate PRs reviewed and merged.
+- [ ] One pass through `pnpm/npm/yarn audit` looking for transitives that snuck in.
+
+### Monthly Dependency Audit
+
+- [ ] Quarterly `pnpm dlx depcheck` / `pip-autoremove` / `go mod tidy` — drop unused.
+- [ ] Review of new direct deps added since last audit — still justified?
+- [ ] Refresh of "abandoned package" check — anyone left maintainership?
+
+### Incident: "Compromised Package"
+
+When a notice drops ("colors.js v1.4.x is malicious"):
+
+1. **Pin LOWER** in your lockfile + redeploy in <2 hours.
+2. **Audit logs** for the time window when the compromised version was deployed.
+3. **Rotate any secrets** the deployment had access to.
+4. **Notify users** if data was at risk.
+5. **Post-mortem** — what could have caught this earlier?
+
+## Common Supply-Chain Mistakes
+
+1. **Lockfile not committed** — non-reproducible builds; transitive surprise.
+2. **`npm install` instead of `npm ci`** in CI — re-resolves; lockfile becomes advisory.
+3. **No `audit` in CI** — vulnerabilities ship to prod.
+4. **Auto-merging Dependabot** without test pass — broken release in 5 minutes.
+5. **GitHub Actions tags pinned** instead of SHAs — tag re-pointed at malicious commit = supply-chain attack.
+6. **Long-lived secrets** in CI — first leak forever.
+7. **Public package install before private check** — dependency confusion.
+8. **No SBOM** — can't quickly answer "are we affected by CVE-X" without grepping every lockfile.
+9. **Pulling Docker `image:latest`** in production — non-reproducible; new "latest" = silent change.
+10. **`curl | sh` install** in CI — full code-execution from a remote server you didn't audit.
+
+## Source Material
+
+- *OWASP CycloneDX*: <https://cyclonedx.org/>
+- *Sigstore*: <https://www.sigstore.dev/>
+- *SLSA framework*: <https://slsa.dev/>
+- *npm provenance*: <https://docs.npmjs.com/generating-provenance-statements>
+- *OSV database*: <https://osv.dev/>
+- *Snyk supply-chain reports* (annual) — current threat landscape data.

core/skills/security-web/scripts/csp-check.sh

@@ -0,0 +1,153 @@
+#!/usr/bin/env bash
+# Probe an HTTP endpoint for Content-Security-Policy + other security
+# headers (HSTS, X-Content-Type-Options, Referrer-Policy, Permissions-Policy,
+# COOP, COEP, X-Frame-Options).
+#
+# Usage:
+#   bash csp-check.sh https://example.com
+#   bash csp-check.sh --strict https://example.com   # fails on missing headers
+#   bash csp-check.sh --json https://example.com
+#
+# Exit codes:
+#   0 = all required headers present (or non-strict mode)
+#   1 = one or more required headers missing (only in --strict)
+#   2 = curl error / bad URL
+
+set -euo pipefail
+
+# Safety: ensure core POSIX tools resolvable even when caller PATH is restricted.
+export PATH="/usr/bin:/bin:/usr/local/bin:${PATH:-}"
+
+STRICT=0
+EMIT_JSON=0
+URL=""
+
+while [ $# -gt 0 ]; do
+  case "$1" in
+    --strict) STRICT=1; shift ;;
+    --json) EMIT_JSON=1; shift ;;
+    -h|--help) sed -n '2,12p' "$0"; exit 0 ;;
+    -*) echo "Unknown flag: $1" >&2; exit 2 ;;
+    *) URL="$1"; shift ;;
+  esac
+done
+
+if [ -z "$URL" ]; then
+  echo "usage: $0 [--strict] [--json] <url>" >&2
+  exit 2
+fi
+
+if ! command -v curl >/dev/null 2>&1; then
+  echo "curl not installed" >&2
+  exit 2
+fi
+
+# Fetch headers only. -I = HEAD; some servers respond differently to HEAD
+# vs GET so also try GET with -X GET and discard body.
+HEADERS=$(curl -sS -L -D - -X GET -o /dev/null --max-time 10 "$URL" 2>&1) || {
+  echo "curl failed for $URL" >&2
+  exit 2
+}
+
+# Normalise: lowercase header names for grep
+headers_lower=$(echo "$HEADERS" | tr 'A-Z' 'a-z')
+
+# Required + recommended headers
+declare -a REQUIRED=(
+  "content-security-policy"
+  "strict-transport-security"
+  "x-content-type-options"
+  "referrer-policy"
+)
+declare -a RECOMMENDED=(
+  "permissions-policy"
+  "cross-origin-opener-policy"
+  "cross-origin-embedder-policy"
+  "x-frame-options"
+)
+
+declare -a MISSING_REQ=()
+declare -a MISSING_REC=()
+declare -A PRESENT=()
+
+check_header() {
+  local h="$1"
+  if echo "$headers_lower" | grep -qE "^${h}:"; then
+    # Extract value (case-insensitive on header)
+    local value
+    value=$(echo "$HEADERS" | grep -iE "^${h}:" | head -1 | sed -E 's/^[^:]+:[[:space:]]*//' | tr -d '\r')
+    PRESENT[$h]="$value"
+    return 0
+  fi
+  return 1
+}
+
+for h in "${REQUIRED[@]}"; do
+  if ! check_header "$h"; then
+    MISSING_REQ+=("$h")
+  fi
+done
+
+for h in "${RECOMMENDED[@]}"; do
+  if ! check_header "$h"; then
+    MISSING_REC+=("$h")
+  fi
+done
+
+# Emit
+if [ "$EMIT_JSON" -eq 1 ]; then
+  # Build JSON manually (no jq dependency)
+  printf '{\n  "url": "%s",\n  "missing_required": [' "$URL"
+  first=1
+  for h in "${MISSING_REQ[@]+"${MISSING_REQ[@]}"}"; do
+    [ $first -eq 0 ] && printf ', '
+    printf '"%s"' "$h"
+    first=0
+  done
+  printf '],\n  "missing_recommended": ['
+  first=1
+  for h in "${MISSING_REC[@]+"${MISSING_REC[@]}"}"; do
+    [ $first -eq 0 ] && printf ', '
+    printf '"%s"' "$h"
+    first=0
+  done
+  printf '],\n  "present": {'
+  first=1
+  for h in "${!PRESENT[@]}"; do
+    [ $first -eq 0 ] && printf ', '
+    # Naive JSON-escape: replace " with \" and \ with \\
+    value="${PRESENT[$h]//\\/\\\\}"
+    value="${value//\"/\\\"}"
+    printf '"%s": "%s"' "$h" "$value"
+    first=0
+  done
+  printf '}\n}\n'
+else
+  echo "Security header probe — $URL"
+  echo
+  if [ "${#MISSING_REQ[@]}" -gt 0 ]; then
+    echo "MISSING (required):"
+    for h in "${MISSING_REQ[@]}"; do
+      echo "  - $h"
+    done
+    echo
+  fi
+  if [ "${#MISSING_REC[@]}" -gt 0 ]; then
+    echo "Missing (recommended):"
+    for h in "${MISSING_REC[@]}"; do
+      echo "  - $h"
+    done
+    echo
+  fi
+  if [ "${#PRESENT[@]}" -gt 0 ]; then
+    echo "Present:"
+    for h in "${!PRESENT[@]}"; do
+      printf "  %-32s %s\n" "$h:" "${PRESENT[$h]}"
+    done
+  fi
+fi
+
+if [ "$STRICT" -eq 1 ] && [ "${#MISSING_REQ[@]}" -gt 0 ]; then
+  exit 1
+fi
+exit 0

core/skills/shell-scripting/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: shell-scripting
+tier: quality
+domain: [universal]
+description: Write production-grade shell and CLI scripts — Bash and Python. Use when authoring or reviewing any script, Makefile target, hook, CI step, or automation that takes input, does work, and reports a result. Enforces runtime arguments (not hardcoded paths), fail-closed error handling, progress/observable output, idempotency, algorithmic efficiency, and precise machine-readable results. Triggers — "write a script", "bash script", "make target", "automate", "cron job", "CLI tool", any `*.sh`/`scripts/*.py`. Pairs with clean-code (naming/structure), deployment-cicd (CI steps), observability (log hygiene), hook-authoring (coding-os hooks).
+globs: ""
+paths: []
+last_reviewed: "2026-06-04"
+versions_ref: versions.json
+---
+
+# Shell & CLI Scripting
+
+A script is a **contract**: given inputs, do exactly one job, report a precise result, fail loud on anything unexpected. A script that hardcodes a path, swallows errors, or prints a paragraph the caller must parse is a liability — it breaks silently in the next environment and taxes every agent that runs it. This skill makes "robust, data-driven, observable" the default shape.
+
+> Scaffold a compliant script instead of hand-writing the boilerplate:
+> `python3 scripts/new_script.py --lang bash --name deploy --root .`
+> Lint an existing one against the discipline:
+> `bash scripts/lint_script.sh path/to/script.sh`
+
+## The seven non-negotiables
+
+Every script — Bash or Python — satisfies all seven. The checklist in [assets/script-checklist.md](assets/script-checklist.md) is the ship gate.
+
+1. **Runtime arguments, never hardcoded.** Inputs come from flags with sane defaults. No literal machine paths, no baked-in hostnames, no magic constants buried in the body.
+2. **Fail-closed.** Any unmet precondition or sub-command failure stops the script with a non-zero exit and a message — never continue on error.
+3. **Idempotent.** Re-running is safe: detect already-done state, refuse to clobber (or require `--force`).
+4. **Observable.** Progress to stderr for anything slow; a final, parseable result (one line or `--json`) on stdout.
+5. **Precise output.** stdout is the *result* a caller consumes; stderr is *narration*. Never mix them.
+6. **Algorithmically honest.** No O(n²) where a set/index is O(n). Stream large inputs; bound memory. State complexity when non-obvious.
+7. **Documented header.** `PURPOSE / INPUT / OUTPUT / DEPENDENCIES / NOTES` at the top — the contract in five lines.
+
+## Bash — the robust preamble (copy, don't retype)
+
+```bash
+#!/usr/bin/env bash
+# deploy.sh — PURPOSE: ... / INPUT: ... / OUTPUT: ... / DEPS: ... / NOTES: ...
+set -euo pipefail          # -e exit on error · -u unset var is error · -o pipefail catch piped failures
+IFS=$'\n\t'                # safe word-splitting (no space-splitting surprises)
+
+cleanup() { rm -f "${_tmp:-}"; }
+trap cleanup EXIT          # run on ANY exit path — success, error, or signal
+```
+
+Why each flag matters — bad→good:
+
+```bash
+# Wrong — silent data loss: cd fails, rm runs in the WRONG directory
+cd "$build_dir"
+rm -rf ./*
+
+# Correct — set -e aborts before rm if cd fails; quoting survives spaces
+set -euo pipefail
+cd "$build_dir"            # aborts here if $build_dir is unset (-u) or missing (-e)
+rm -rf -- "${build_dir:?build_dir required}"/*
+```
+
+```bash
+# Wrong — pipefail off: the pipeline "succeeds" even though curl failed
+curl -s "$url" | jq .version          # exit 0 even on 404
+
+# Correct
+set -o pipefail
+curl -fsS "$url" | jq .version        # -f makes curl fail on HTTP error; pipefail propagates it
+```
+
+Quoting + `grep` exit-code traps (the two that bite every script): always `"$var"`, and a `grep`/`grep -c` that matches nothing returns exit 1 — under `set -e` that kills the script. Guard it: `count=$(grep -c foo file || true)`. Full rules → [references/bash-robustness.md](references/bash-robustness.md).
+
+## Arguments — `getopts` (Bash) / `argparse` (Python)
+
+```bash
+# Bash — flags with defaults, a usage(), and a required-arg check
+usage() { echo "usage: $0 --target <env> [--dry-run]" >&2; exit 2; }
+target="" ; dry_run=0
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --target) target="${2:?--target needs a value}"; shift 2 ;;
+    --dry-run) dry_run=1; shift ;;
+    -h|--help) usage ;;
+    *) echo "unknown arg: $1" >&2; usage ;;
+  esac
+done
+[[ -n "$target" ]] || { echo "error: --target is required" >&2; usage; }
+```
+
+Python scripts use `argparse` with `--root` defaulting to a consumer-relative path (`src/backend`), never an absolute one. Full comparison + when to graduate from Bash to Python → [references/argument-parsing.md](references/argument-parsing.md).
+
+## Progress + result discipline
+
+```bash
+log() { printf '%s\n' "$*" >&2; }        # narration → stderr
+log "[1/3] fetching..."                    # progress the caller can ignore
+log "[2/3] transforming..."
+printf '{"changed":%d,"skipped":%d}\n' "$changed" "$skipped"   # result → stdout, parseable
+```
+
+The rule that collapses agent cost: **emit the minimum the caller needs to decide the next step, not a transcript.** A script that prints one JSON line replaces ten tool calls the agent would otherwise spend re-deriving state. Quiet by default; `--verbose` opts into detail.
+
+## When Bash, when Python
+
+| Reach for Bash | Reach for Python |
+|---|---|
+| ≤ ~50 lines, glue of existing CLIs | parsing/transforming structured data (JSON, CSV) |
+| process orchestration, file moves | non-trivial control flow, data structures |
+| no arrays-of-structs, no math | needs tests, types, or stdlib beyond coreutils |
+
+Past ~50 lines or the first associative-array-of-records, graduate to Python. A 200-line Bash script with nested `eval` is a maintenance trap — the line where you reach for `eval` is the line you should have been in Python.
+
+## `make` targets
+
+A Makefile target is a script too: `.PHONY` it, one job per target, `@` to quiet the echo, fail-closed (make stops on non-zero by default — don't `|| true` away real failures). Document with `## comment` so `make help` lists it.
+
+## Anti-patterns (reject on sight)
+
+- Hardcoded `/Users/...`, `/home/...`, or a literal hostname → take a flag.
+- `set -e` absent, or defeated by a trailing `|| true` on a command whose failure matters.
+- `cmd2` running after `cmd1` failed because there is no `&&` and no `set -e`.
+- stdout polluted with progress so the caller can't parse the result.
+- Re-running the script doubles the effect (not idempotent).
+- Parsing `ls` output, or `for f in $(ls)` — use a glob or `find -print0 | while read -d ''`.
+- `eval` on interpolated input — almost always a quoting bug or a Python signal.
+
+## See also
+
+- [references/bash-robustness.md](references/bash-robustness.md) — strict mode, traps, quoting, the `grep` exit trap.
+- [references/argument-parsing.md](references/argument-parsing.md) — `getopts` vs `argparse`, the Bash→Python line.
+- [assets/script-checklist.md](assets/script-checklist.md) — the ship gate.
+- [docs/playbooks/skill-authoring.md](../../../docs/playbooks/skill-authoring.md) § scripts contract — why every skill's scripts obey this.

core/skills/shell-scripting/assets/script-checklist.md

@@ -0,0 +1,33 @@
+<!-- domain:UNIVERSAL | layer:asset | ssot:false | updated:2026-06-04 -->
+# Script Ship Checklist
+
+Run before committing any script, hook, or `make` target. Every box ticked, or it does not ship.
+
+## The seven non-negotiables
+- [ ] **Arguments, not constants** — every input is a flag with a sane default; zero hardcoded machine paths / hosts / magic numbers.
+- [ ] **Fail-closed** — Bash: `set -euo pipefail`. Python: explicit non-zero exit on any unmet precondition. No `|| true` on a failure that matters.
+- [ ] **Idempotent** — re-running is safe; already-done state is detected; clobbering requires `--force`.
+- [ ] **Observable** — progress to stderr for slow work; final parseable result (one line or `--json`) on stdout.
+- [ ] **stdout = result, stderr = narration** — never mixed.
+- [ ] **Algorithmically honest** — no O(n²) where a set/index works; large inputs streamed; memory bounded.
+- [ ] **Header present** — `PURPOSE / INPUT / OUTPUT / DEPENDENCIES / NOTES`.
+
+## Bash-specific
+- [ ] Shebang `#!/usr/bin/env bash`.
+- [ ] `IFS=$'\n\t'` when word-splitting matters.
+- [ ] `trap cleanup EXIT` if any temp file / lock is created.
+- [ ] All expansions quoted: `"$var"`, `"${arr[@]}"`, `"$@"`.
+- [ ] `grep`/`grep -c` that may match nothing wrapped with `|| true`.
+- [ ] No `for f in $(ls ...)` — glob or `find -print0`.
+- [ ] `shellcheck -S warning` clean; `shfmt` formatted.
+
+## Python-specific
+- [ ] `argparse` with explicit `main(argv)` (testable).
+- [ ] `--root` / path defaults are consumer-relative, never absolute.
+- [ ] stdlib-only unless a dependency is justified.
+- [ ] Pure logic separated from IO so it unit-tests without network/fs.
+
+## Verify
+- [ ] `bash scripts/lint_script.sh <file>` → `0 issue(s)`.
+- [ ] Ran it twice — second run is a no-op (idempotent).
+- [ ] `make verify-hooks` green (for hooks / `src/core/**` scripts).

core/skills/shell-scripting/references/argument-parsing.md

@@ -0,0 +1,84 @@
+<!-- domain:UNIVERSAL | layer:reference | ssot:true | updated:2026-06-04 -->
+# Argument Parsing — `getopts`, manual `case`, and `argparse`
+
+> P: How to take runtime arguments correctly in Bash and Python, and exactly when to abandon Bash for Python.
+> R: Any script that takes a flag, a path, or a mode.
+> S: A zero-argument one-shot (rare — most "one-shots" grow a flag within a week).
+> N: [SKILL.md](../SKILL.md), [bash-robustness.md](bash-robustness.md)
+
+> Nav: [Skill](../SKILL.md)
+
+## Bash — manual `while/case` (preferred for long flags)
+
+`getopts` only handles single-letter flags (`-t`) and no `--long` forms. For readable scripts use a manual loop:
+
+```bash
+usage() { echo "usage: $0 --target <env> [--workers N] [--dry-run]" >&2; exit 2; }
+target="" ; workers=4 ; dry_run=0
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --target)  target="${2:?--target needs a value}"; shift 2 ;;
+    --workers) workers="${2:?--workers needs a value}"; shift 2 ;;
+    --dry-run) dry_run=1; shift ;;
+    -h|--help) usage ;;
+    --) shift; break ;;                 # explicit end-of-flags
+    -*) echo "unknown flag: $1" >&2; usage ;;
+    *) break ;;                          # first positional
+  esac
+done
+[[ -n "$target" ]] || { echo "error: --target required" >&2; usage; }
+```
+
+Three rules: every flag has a default, a missing required flag prints `usage` and exits non-zero, and `${2:?msg}` guarantees a value-taking flag was actually given one.
+
+### `getopts` — when single-letter is enough
+
+```bash
+while getopts ":t:w:nh" opt; do
+  case "$opt" in
+    t) target="$OPTARG" ;;
+    w) workers="$OPTARG" ;;
+    n) dry_run=1 ;;
+    h) usage ;;
+    :) echo "-$OPTARG needs a value" >&2; usage ;;
+    \?) echo "unknown -$OPTARG" >&2; usage ;;
+  esac
+done
+```
+
+## Defaults must be consumer-relative, never absolute
+
+```bash
+# Wrong — breaks on every machine but the author's
+root="/Users/me/project/src/backend"
+
+# Correct — relative default, overridable
+root="${1:-src/backend}"
+```
+
+Python mirror: `parser.add_argument("--root", default="src/backend", type=Path)`. A script that bakes in `/Users/...` or `/home/...` fails the lint and the review.
+
+## Python — `argparse` (the default past ~50 lines)
+
+```python
+parser = argparse.ArgumentParser(description=__doc__.split("\n")[0])
+parser.add_argument("--root", default="src/backend", type=Path)
+parser.add_argument("--workers", default=4, type=int)
+parser.add_argument("--dry-run", action="store_true")
+parser.add_argument("--json", action="store_true", dest="as_json")
+args = parser.parse_args(argv)        # pass argv explicitly so it's testable
+```
+
+`description=__doc__.split("\n")[0]` reuses the module docstring's first line as `--help` text — one source for both. Take `argv: list[str]` in `main(argv)` rather than reading `sys.argv` inside, so the parser is unit-testable.
+
+## The Bash → Python line
+
+Graduate to Python the moment **any** of these appears:
+
+- structured data in/out (JSON, CSV, an API response you must field-access);
+- an array of records / an associative array of structs;
+- arithmetic beyond `$(( ))` increments;
+- you want unit tests or type hints;
+- the script crosses ~50 lines or you reach for `eval`.
+
+A 200-line Bash script with nested `eval` and string-built JSON is a rewrite waiting to happen. Spend the 20 minutes now.

core/skills/shell-scripting/references/bash-robustness.md

@@ -0,0 +1,78 @@
+<!-- domain:UNIVERSAL | layer:reference | ssot:true | updated:2026-06-04 -->
+# Bash Robustness — Strict Mode, Traps, Quoting
+
+> P: The exact failure modes strict mode prevents and the idioms that survive spaces, empty matches, and signals.
+> R: Writing or reviewing any Bash longer than a one-liner.
+> S: Pure Python scripts — see [argument-parsing.md](argument-parsing.md) for the Bash→Python line.
+> N: [SKILL.md](../SKILL.md), [script-checklist.md](../assets/script-checklist.md)
+
+> Nav: [Skill](../SKILL.md)
+
+## Strict mode — what each flag actually prevents
+
+| Flag | Without it | With it |
+|---|---|---|
+| `set -e` | a failed command is ignored; the script ploughs on with bad state | first non-zero exit aborts (except in conditionals) |
+| `set -u` | a typo'd `$VARNAME` expands to empty → `rm -rf $DIR/` becomes `rm -rf /` | unset variable is a hard error |
+| `set -o pipefail` | `false | true` exits 0 — a failed `curl` in a pipe looks successful | the pipeline's exit is the last non-zero |
+| `IFS=$'\n\t'` | word-splitting on spaces mangles filenames with spaces | splits only on newline/tab |
+
+`set -euo pipefail` is the floor. It is not magic — know its three escape hatches:
+
+1. **Conditionals are exempt.** `if grep -q x f; then` does not abort on no-match — that is correct. But a *bare* `grep -q x f` on its own line WILL abort under `-e` when there is no match.
+2. **`local x=$(cmd)` hides the exit code** — `local` returns 0, masking `cmd`'s failure. Split: `local x; x=$(cmd)`.
+3. **`cmd || true`** deliberately swallows failure — use ONLY when the failure is genuinely fine (e.g. a `grep -c` that legitimately matches nothing). Never use it to silence a failure that matters.
+
+## The `grep` / `find` exit-code trap
+
+`grep` returns exit 1 when it matches nothing; `grep -c` likewise. Under `set -e` that aborts the script even though "zero matches" is a valid answer.
+
+```bash
+# Wrong — aborts the whole script when the pattern is simply absent
+count=$(grep -c ERROR app.log)
+
+# Correct — capture the count, tolerate zero matches
+count=$(grep -c ERROR app.log || true)
+[[ -z "$count" ]] && count=0
+```
+
+## Traps — cleanup on every exit path
+
+```bash
+_tmp="$(mktemp)"
+cleanup() { rm -f "$_tmp"; }
+trap cleanup EXIT          # runs on success, error (-e), AND Ctrl-C / SIGTERM
+```
+
+`EXIT` covers normal return + error abort + most signals. Add `trap 'cleanup; exit 130' INT` only when you need a distinct exit code per signal. Never leave temp files behind for the next run to trip over.
+
+## Quoting — the rule with no exceptions
+
+Always `"$var"`, always `"${array[@]}"`, always `"$@"` (not `$*`). Unquoted expansion re-splits on `IFS` and glob-expands — the source of "works on my machine, deletes your repo on theirs".
+
+```bash
+# Wrong — a path with a space becomes two arguments
+cp $src $dst
+
+# Correct
+cp -- "$src" "$dst"          # -- stops option parsing if $src starts with '-'
+```
+
+## Iterating files — never parse `ls`
+
+```bash
+# Wrong — breaks on spaces, newlines, globs in names
+for f in $(ls *.log); do ... done
+
+# Correct — NUL-delimited, survives any filename
+while IFS= read -r -d '' f; do
+  process "$f"
+done < <(find . -name '*.log' -print0)
+```
+
+## Tooling
+
+- **shellcheck** (`koalaman/shellcheck`, pinned in [versions.json](../versions.json)) — static analysis; treat warnings as errors in CI. `make verify-hooks` runs it across the repo's hooks.
+- **shfmt** (`mvdan/sh`) — deterministic formatter; `shfmt -i 2 -w script.sh`.
+
+Run both in the script's CI step; a script that shellcheck flags is not shippable.