@gspothq/cli 0.0.0-stage → 0.1.1

package/configurations/infrastructure/openapi/rules/OPENAPI.md

@@ -0,0 +1,39 @@
+# OpenAPI
+
+## Public contracts
+
+When the project publishes OpenAPI, its document describes the runtime API.
+
+- Keep required fields, types, accepted media types, status codes, and security requirements
+  consistent between the document and the implementation.
+- Preserve the chosen schema library and the command that writes the OpenAPI document.
+- Keep request and response examples valid against their schemas.
+- Document error responses and nullable or optional values precisely.
+
+This OpenAPI 3.1 fragment describes a query limit. Its bounds and default must also hold
+when the server handles the request:
+
+```yaml
+parameters:
+  - name: limit
+    in: query
+    required: false
+    schema:
+      type: integer
+      minimum: 1
+      maximum: 100
+      default: 50
+```
+
+## Contract tests
+
+When you write contract tests:
+
+- Validate representative success and error responses against the published schemas.
+- Exercise invalid body, query, and route values through HTTP and assert their declared errors.
+- Verify authentication and authorization requirements for protected operations.
+- Test the public response. Assert its status and content type.
+- Keep generated schemas and their inputs synchronized through the existing generator.
+
+An assertion that checks only selected response fields does not prove that the whole response
+satisfies its schema. Use the project's schema validator for that claim.

package/configurations/infrastructure/xcode/manifest.toml

@@ -0,0 +1,131 @@
+allowed_words = ["Xcode"]
+[configuration]
+title = "Xcode"
+suggests = ["swift"]
+description = "An Xcode project: property lists that parse, build settings files, and complete string catalogs. Asset catalogs hold their images, test targets sit in a plan, sources belong to a target, and entitlements stay on a list."
+
+[detect]
+paths = ["**/*.xcodeproj/project.pbxproj"]
+project_files = ["*.xcodeproj"]
+
+[files]
+extensions = [".plist", ".entitlements", ".xcconfig", ".xcstrings", ".storyboard", ".xib"]
+paths = ["**/project.pbxproj", "**/*.xcscheme", "**/*.xctestplan", "**/*.xcassets/**/Contents.json"]
+
+[[tool]]
+name = "plutil"
+install_hint = "install Xcode from the App Store"
+system = true
+builds = ["macos"]
+crash_pattern = "couldn['’]t be opened"
+
+[[check]]
+name = "plutil"
+example = "A plist containing an unclosed dictionary fails native validation. Close the dictionary and plist elements, then rerun with plutil available on a declared platform."
+level = "recommended"
+stage = "commit"
+command = ["plutil", "-lint", "{files}"]
+files = { extensions = [".plist", ".entitlements"] }
+output = { format = "regex", pattern = "^(?<file>[^:]+): (?<message>(?!OK$).+)$" }
+summary = "Parses every property list and entitlements file with plutil."
+why = "A broken plist fails the build or, worse, ships an app whose settings silently fell back to defaults."
+help = "Fix the element plutil names."
+
+[[check]]
+name = "xcconfig"
+example = "A non-comment line `PRODUCT_NAME App` in an `.xcconfig` file lacks an assignment operator. Change it to `PRODUCT_NAME = App`."
+level = "recommended"
+stage = "commit"
+runs = "scope"
+files = { extensions = [".xcconfig"] }
+summary = "Checks that every line of a build settings file is a setting, an include, or a comment."
+why = "Xcode ignores a line it cannot read, so a typo turns a setting off without a word."
+help = "Write the line as a name, an equals sign, and a value."
+
+[[check]]
+name = "xcstrings"
+example = "A string catalog entry with one translated locale and an absent required locale reports the missing translation. Add that locale and its translation, or explicitly mark the string as not translated when that is the intended catalog state."
+level = "recommended"
+stage = "commit"
+runs = "scope"
+files = { extensions = [".xcstrings"] }
+summary = "Checks that every string catalog parses, and that every string has a translation for every locale the catalog uses."
+why = "A string with no translation shows its source language in the middle of a translated screen."
+help = "Add the translation, or mark the string as not translated in the catalog."
+
+[[check]]
+name = "assets"
+example = "A `Contents.json` image entry naming `icon.png` reports a missing asset when that file does not exist. Add the intended image beside the manifest or remove the obsolete entry."
+level = "recommended"
+stage = "commit"
+runs = "scope"
+files = { paths = ["**/*.xcassets/**"], extensions = [".swift"] }
+summary = "Checks that every asset Contents.json parses and that every image set holds the images it names."
+why = "An image set with no image draws nothing at run time."
+help = "Add the image or delete the asset."
+
+[[check]]
+name = "unused-assets"
+example = "An asset set named only in an Xcode build setting counts as used. An asset that no source or build setting names reports an unused-asset finding."
+level = "all"
+stage = "commit"
+runs = "scope"
+files = { paths = ["**/*.xcassets/**"], extensions = [".swift", ".storyboard", ".xib", ".plist", ".pbxproj", ".xcconfig"] }
+summary = "At level all, finds asset sets that no source or Xcode build setting names."
+why = "An asset nobody names ships in the app for nothing."
+help = "Delete the asset or name it where it is used. For an accepted asset selected at runtime, run gspot ignore xcode/unused-assets --rule unused-asset --paths `<glob>` --reason \"`<why>`\"."
+
+[[check]]
+name = "test-plans"
+example = "A test target absent from the test plan used by its scheme reports missing coverage by the plan. Add that target to the plan and point the scheme at the plan."
+level = "all"
+stage = "commit"
+runs = "scope"
+summary = "Checks that every shared scheme that runs tests names a test plan, and that every test target is in a plan."
+why = "A test target outside every plan never runs in CI, and its tests rot while they look present."
+help = "Add the target to a test plan, and point the scheme at the plan."
+
+[[check]]
+name = "files-without-target"
+example = "A Swift source file under the project that belongs to no target reports an orphan source. Add the file to its intended target or delete the unused source. Remove project references to files that no longer exist."
+level = "recommended"
+stage = "commit"
+runs = "scope"
+files = { extensions = [".swift"], paths = ["**/project.pbxproj"] }
+summary = "Compares the Swift files in the tree with the files the project names: a file in no target, and a target file that is gone."
+why = "A Swift file in no target is never compiled, so it breaks without anyone seeing it."
+help = "Add the file to a target or delete it, and remove the reference to a file that is gone."
+
+[[check]]
+name = "symlinks"
+when = { git = true }
+example = "A source directory represented by a symlink reports a project symlink finding. Replace the link with the intended repository-owned directory and update project references."
+level = "all"
+stage = "commit"
+runs = "scope"
+summary = "Reports every tracked symlink beside or under an Xcode project, with where it points."
+why = "Xcode, git, and each lint tool follow a symlink their own way, so one file is checked twice or never."
+help = "Replace the symlink with the folder it points at, or ignore the path with a reason."
+
+[[check]]
+name = "entitlements"
+example = "An entitlement enabled in an `.entitlements` file but absent from `xcode.allowed_entitlements` reports a settings finding. Remove an unnecessary entitlement, or explicitly allow the required entitlement in settings."
+level = "recommended"
+when = { setting = "xcode.allowed_entitlements" }
+stage = "commit"
+runs = "scope"
+files = { extensions = [".entitlements"] }
+summary = "Checks that every entitlement is on xcode.allowed_entitlements, when the settings hold that list."
+why = "An entitlement is a capability the system grants the app, and a new one deserves a review of its own."
+help = "Remove the entitlement, or add it to xcode.allowed_entitlements."
+
+[[check]]
+name = "app-transport-security"
+example = "An Info.plist enabling `NSAllowsArbitraryLoads` disables transport protection broadly and reports a finding. Remove that key. If one host requires an exception, declare only the host-specific exception."
+level = "recommended"
+stage = "commit"
+runs = "scope"
+files = { extensions = [".plist"] }
+summary = "Refuses a property list that allows arbitrary loads, which turns transport security off for every host."
+why = "With arbitrary loads the app speaks plain HTTP to anyone, and one forgotten debug setting ships it."
+help = "Remove the key, and add an exception for the one host that needs it."

package/configurations/infrastructure/xcode/rules/XCODE.md

@@ -0,0 +1,34 @@
+# Xcode
+
+## Project settings
+
+- `SWIFT_STRICT_CONCURRENCY = complete`. Set the upcoming-feature flags the project adopts in
+  the project, not per file.
+- Share schemes needed by collaborators and CI. Keep personal scheme state out of the repository.
+- Set deployment targets deliberately for each supported product. Verify compatibility
+  between apps, extensions, frameworks, and package dependencies.
+
+## Files
+
+- Keep source and resource membership consistent with the intended targets. Avoid duplicate
+  build entries; preserve synchronized groups where the project uses them.
+- Put images and named colors in asset catalogs when the platform supports their required format.
+  Keep other resources in the appropriate bundle locations.
+- `Info.plist` values that vary by configuration come from build settings
+  such as `$(PRODUCT_BUNDLE_IDENTIFIER)`, not from edited plist copies.
+
+## Build phases and scripts
+
+- Run-script phases declare their interpreter and pass the checks for that language.
+- Every run-script phase declares its input and output files so the build system can skip it.
+- No network access or code generation without declared outputs.
+- The linter and the formatter run before commit, not as build phases that fail the build twice.
+
+## Project organization
+
+<!-- level: all -->
+
+Keep shared build settings in the project or `.xcconfig` file. A target overrides only
+what differs. Preserve the project's chosen modules and packages; do not introduce
+a package only to enforce a directory layout. Keep substantial build-script logic in a
+repository file its language tools can check.

package/configurations/language/bash/manifest.toml

@@ -0,0 +1,261 @@
+allowed_words = ["Bash", "ShellCheck", "tree-sitter"]
+[configuration]
+title = "Bash, zsh, and Bats scripts"
+suggests = []
+description = "Shell scripts, hooks and task files: ShellCheck, shfmt, a syntax pass, and the structure rules for shell."
+
+[detect]
+extensions = [".sh", ".bash", ".zsh", ".bats"]
+shebangs = ["shell"]
+
+[files]
+extensions = [".sh", ".bash", ".zsh", ".bats"]
+tags = ["shebang:shell"]
+
+[[tool]]
+name = "shellcheck"
+refused_options = [
+    { paths = ["enable", "disable"], message = "ShellCheck rule selection comes from level recommended or all and gspot ignore. Remove enable and disable from tools.shellcheck.extra.value." },
+]
+rule_url = "https://www.shellcheck.net/wiki/{rule}"
+suppression = { marker = "\\bshellcheck +disable=", reason = "# ?reason: (?<reason>\\S.*)" }
+version = "0.11.0"
+mise = "shellcheck"
+brew = "shellcheck"
+apt = "shellcheck"
+winget = "koalaman.shellcheck"
+scoop = "shellcheck"
+github = { name = "koalaman/shellcheck", version = "v0.11.0" }
+[[tool.replace]]
+file = ".shellcheckrc"
+shared = false
+
+[[tool]]
+name = "shfmt"
+version = "3.12.0"
+mise = "shfmt"
+brew = "shfmt"
+winget = "mvdan.shfmt"
+scoop = "shfmt"
+github = { name = "mvdan/sh", version = "v3.12.0" }
+
+[[tool]]
+name = "bash"
+min_version = "4.4"
+install_hint = "install Bash 4.4 or newer, such as with brew install bash on macOS"
+system = true
+version_command = ["--version"]
+version_pattern = "version (\\d+\\.\\d+(?:\\.\\d+)?)"
+
+[[tool]]
+name = "zsh"
+system = true
+
+[[tool]]
+name = "bats"
+system = true
+
+[[tool_file]]
+target = ".gspot/config/shellcheckrc"
+tool = "shellcheck"
+rule_keys = ["enable", "disable"]
+per_scope = true
+
+[[check]]
+name = "bash-syntax"
+example = "In `greet.sh`, `if then` has no condition. Use a real test: `if [ -f \"$file\" ]; then printf \"%s\\n\" \"$file\"; fi`, then rerun the syntax check."
+level = "recommended"
+stage = "commit"
+command = ["bash", "-n", "{file}"]
+files = { tags = ["bash"] }
+output = { format = "regex", pattern = "^.*: line (?<line>\\d+): (?<message>.*)$" }
+summary = "Checks that Bash scripts parse before running them."
+why = "A script with a syntax error stops at the broken line, sometimes after it has already done half its work."
+help = "Open the file at the line bash names and fix the quoting, bracket, or keyword it complains about."
+
+[[check]]
+name = "zsh-syntax"
+example = "In a Zsh script, `if then` has no condition. Use a real test: `if [[ -f \"$file\" ]]; then print -r -- \"$file\"; fi`, then rerun with Zsh installed."
+level = "recommended"
+stage = "commit"
+command = ["zsh", "-n", "{file}"]
+files = { tags = ["zsh"] }
+output = { format = "regex", pattern = "^(?<file>[^:]+):(?<line>\\d+):\\s*(?<message>.*)$" }
+summary = "Checks Zsh syntax with the Zsh interpreter."
+why = "Zsh syntax differs from Bash, so a Bash parser rejects valid Zsh programs."
+help = "Fix the syntax at the line Zsh reports. Install zsh when the command is missing."
+
+[[check]]
+name = "bats-syntax"
+example = "In a `.bats` file, an unterminated `@test \"greeting\" {` block fails parsing. Complete the test body and close it with `}` before rerunning with Bats installed."
+level = "recommended"
+stage = "commit"
+command = ["bats", "--count", "{file}"]
+# Bats parses the file with the bash on PATH, and under Bash 3.2 it passes a file that does not parse.
+tool = ["bats", "bash"]
+files = { tags = ["bats"] }
+output = { format = "regex", pattern = "^# (?<file>[^:]+): line (?<line>\\d+): (?<message>.*)$" }
+summary = "Parses Bats test files while counting their test cases."
+why = "Bats test declarations need the Bats parser before Bash can read them."
+help = "Fix the syntax reported by Bats. Install bats-core when the command is missing."
+
+[[check]]
+name = "shellcheck"
+example = "In a Bash script, `printf \"%s\\n\" $name` reports SC2086 because the expansion permits word splitting and globbing. Use `printf \"%s\\n\" \"$name\"` to pass the value as one argument."
+level = "recommended"
+stage = "commit"
+files = { tags = ["bash", "sh", "bats"] }
+command = ["shellcheck", "--rcfile", "{tool_file:shellcheckrc}", "--severity=style", "--check-sourced", "--format=gcc", "{files}"]
+exit_codes = [1]
+output = { format = "regex", pattern = "^(?<file>[^:]+):(?<line>\\d+):(?<column>\\d+): (?:note|warning|error|style): (?<message>.*?) \\[(?<rule>SC\\d+)\\]$" }
+summary = "Runs ShellCheck over shell scripts and sourced files, adding stable optional ShellCheck rules at level all."
+why = "ShellCheck catches the quoting, globbing and exit-status mistakes that make shell scripts fail on the one input nobody tested."
+help = "Read the SC code in the finding; gspot explain shellcheck/SC2086 links to its page. Turn one code off with gspot ignore bash/shellcheck --rule SC2086 --reason \"`<why>`\"."
+
+[[check]]
+name = "shfmt"
+example = "In a script, `if true;then echo hello;fi` differs from shfmt output. Run the configured formatter to add the required spacing and block layout, then rerun the check."
+level = "recommended"
+stage = "commit"
+files = { tags = ["bash", "sh", "bats"] }
+command = ["shfmt", "-d", "-i", "{indent}", "-ci", "-s", "{files}"]
+fix = ["shfmt", "-w", "-i", "{indent}", "-ci", "-s", "{files}"]
+output = { format = "regex", pattern = "^(?:--- )?(?<file>.+?)(?:\\.orig$|:(?<line>\\d+):(?<column>\\d+): (?<message>.+)$)", message = "This script is not formatted the way shfmt formats it.", fixable = "^--- " }
+summary = "Checks that every shell script is formatted the way shfmt formats it."
+why = "One formatter means diffs show what changed, not how someone's editor indents."
+help = "Run gspot check --fix to format every script, or shfmt -w on one file."
+
+[[check]]
+name = "script-layout"
+example = "An executable Bash script without `set -euo pipefail` reports a strict-mode finding. Put strict mode before the first command and, when the script defines functions, call the documented `main` function last."
+level = "all"
+stage = "commit"
+summary = "Checks the contract every Bash script keeps: the shebang, strict mode, a main called last when functions are defined, declarative libraries, cleaned-up temporary files."
+why = "A script that skips strict mode or hides its runtime fails on the machine where it matters, silently."
+help = "Open with the shebang and run set -euo pipefail first. When an executable defines functions, end it with a call to main."
+
+[[check]]
+name = "doc-comments"
+example = "A function `_quiet() { printf \"%s\\n\" \"Hello\"; }` without a preceding description reports a missing comment. Add `# _quiet: prints a greeting.` immediately above the function. Other structural checks still apply."
+level = "all"
+stage = "commit"
+summary = "Checks that every shell function announces itself in a comment above it that says more than its name."
+why = "A function with no summary makes the reader run it in their head; a vague summary is a summary nobody will trust."
+help = "Write \"# name: what it does\" above the function; when it carries doc sections, keep Globals, Arguments, Outputs, Returns in that order."
+
+[[check]]
+name = "unused-functions"
+example = "A private shell function `_orphan` that no script calls reports an unused-function finding. Delete the unused definition. If an external hook requires the function, record that contract with `gspot ignore` and a reason."
+level = "recommended"
+stage = "commit"
+runs = "scope"
+summary = "Finds shell functions no script in the scope calls."
+why = "ShellCheck checks one file; this check follows calls across every script in the scope."
+help = "Delete the function. For a required hook entry point, run `gspot ignore bash/unused-functions --paths <file> --reason <why>`."
+
+[[check]]
+name = "unread-arguments"
+example = "A call `_deaf one two` whose function never reads positional arguments reports dead parameters. If both arguments are unnecessary, remove them from the call. Otherwise read and use the arguments in the function."
+level = "recommended"
+stage = "commit"
+runs = "scope"
+summary = "Finds shell functions called with arguments they never read."
+why = "A caller that passes an argument expects it to affect the result. An unread argument misleads the caller."
+help = "Read the argument in the function, or drop it from every call."
+
+[[check]]
+name = "source-order"
+example = "A block of `source` lines that is not ordered shortest first reports the sorted order. Reorder the lines."
+level = "all"
+stage = "commit"
+summary = "Checks that the source statements of a block go shortest first, alphabetically among lines of one length."
+why = "One order for every block means a reader never searches it."
+help = "Reorder the source statements shortest first."
+
+[[check]]
+name = "private-prefix"
+example = "A function `build_it` called only from its own script reports a missing private prefix. Rename it `_build_it` and update each local call. A function called from another script keeps its public name."
+level = "all"
+stage = "commit"
+runs = "scope"
+summary = "Checks that a shell function no other file calls starts with an underscore, and that an underscore function is not called from outside."
+why = "The underscore tells a reader what the file publishes without reading every caller."
+help = "Rename the function with a leading underscore, or drop the underscore when another file calls it."
+
+[[check]]
+name = "function-size"
+example = "A function over `limits.bash.function_lines`, `limits.bash.branches`, `limits.bash.nesting`, or `limits.bash.assignments` reports the count and the ceiling under `function-lines`, `branches`, `nesting`, or `assignments`. Split the function by the job, then rerun."
+level = "all"
+stage = "commit"
+summary = "Checks every shell function against the size ceilings: code lines, branches, nesting, and assignments."
+why = "A long script holds more than one job, and a function with many branches or assignments is several functions with one name."
+help = "Split the script or the function, or raise the named limits.bash setting with a reason."
+
+[[check]]
+name = "wrappers"
+example = "A short launcher containing only `exec bash scripts/build.sh` reports a forwarding-wrapper finding. Invoke `scripts/build.sh` directly and remove the redundant launcher."
+level = "all"
+stage = "commit"
+summary = "Finds forwarding wrappers and compatibility aliases in shell scripts."
+why = "A wrapper is a second entry point that drifts from the first."
+help = "Call the target script directly and delete the redundant launcher or alias."
+
+[[check]]
+name = "inline-scripts"
+example = "A shell heredoc containing a Python program reports embedded code. Move the program into a `.py` file and invoke that file from the shell script."
+level = "all"
+stage = "commit"
+summary = "Finds inline Python, Node, and generated-script heredocs in shell scripts."
+why = "Code inside a heredoc is checked by nothing."
+help = "Move the embedded code into its own file and run that."
+
+[[check]]
+name = "ssh-blocks"
+example = "An anonymous SSH heredoc reports a remote-block finding. Move the remote operation into a named function with a comment that explains its purpose, then invoke that function through the supported remote call."
+level = "all"
+stage = "commit"
+summary = "Checks that ssh heredocs are documented."
+why = "A remote command block with no name is the hardest thing in a script to test or reuse."
+help = "Move the block into a named function and write \"# name: what it does\" above it."
+
+[[check]]
+name = "variable-defaults"
+example = "A default such as `${PORT:-8080}` outside a declared configuration owner reports a misplaced default. Set the default in a path listed in `architecture.roles.env` and consume the configured value elsewhere."
+level = "all"
+stage = "commit"
+summary = "Finds variable defaults of the form name:-value outside the configuration owners."
+why = "A default set in three places is three settings with one name."
+help = "Set the default in a configuration owner named under architecture.roles.env and read the variable everywhere else."
+
+[[check]]
+name = "include-guards"
+example = "A sourced configuration owner without a load guard reports a guard finding. Begin it with `[[ -n ${APP_CONFIG_READY:-} ]] && return 0`, followed by `readonly APP_CONFIG_READY=1`, before declaring its configuration."
+level = "all"
+stage = "commit"
+runs = "scope"
+summary = "Checks that each script in architecture.roles.env starts with an include guard of its own."
+why = "A configuration file sourced twice runs its side effects twice."
+help = "Open the owner with [[ -n ${NAME_READY:-} ]] && return 0 and then readonly NAME_READY=1, with a guard name no other owner uses."
+
+[[check]]
+name = "safety"
+example = "A `killall worker` command reports broad-kill. Target the specific process, or ignore that rule for the owning script with a reason."
+level = "recommended"
+stage = "commit"
+summary = "Finds broad process kills and recursive deletes, except traps that remove mktemp paths. At all, it also reports discarded failures."
+why = "Each of these is a way a script destroys something it did not mean to and says nothing."
+help = "Handle the failure. For required cleanup, use gspot ignore bash/safety with --rule, --paths and --reason."
+
+[[naming.override]]
+paths = ["**"]
+languages = ["bash"]
+categories = ["variables"]
+allowed_names = ["IFS", "OPTARG", "OPTIND", "EUID", "UID", "PPID", "RANDOM", "SECONDS", "LINENO", "BASH_SOURCE", "BASH_REMATCH", "BASH_VERSION", "BASH_VERSINFO", "FUNCNAME", "PIPESTATUS", "REPLY", "CDPATH", "OLDPWD", "SHLVL", "HOSTNAME", "OSTYPE", "MACHTYPE", "COLUMNS", "LINES"]
+reason = "The shell defines these variable names."
+
+[[naming.override]]
+paths = ["**"]
+languages = ["bash"]
+categories = ["functions", "variables", "constants", "methods", "attributes"]
+ignored_prefix = "^_+"
+reason = "A leading underscore marks a private shell declaration."

package/configurations/language/bash/rules/BASH.md

@@ -0,0 +1,106 @@
+# Bash
+
+## Bash scope
+
+<!-- level: all -->
+
+Bash orchestrates commands as glue code and does not build application logic. Prefer
+small scripts with explicit inputs, explicit outputs, and clear failure behavior.
+Treat every path, argument, environment value, command output, and user input as unsafe until
+quoted, validated, or parsed by a structured tool. A script that builds, deploys, deletes, or
+publishes artifacts makes its inputs, effects, and failure behavior explicit.
+
+`set -euo pipefail` does not replace checks around dangerous commands. Keep CI YAML and package
+scripts short. Put longer logic in a script file the checks can lint.
+
+## Bash tasks
+
+<!-- level: all -->
+
+Use Bash when the script mostly calls other command-line tools or wires together
+installation, lint, build, runtime, publication, or cleanup steps. Use it to validate the
+environment and dispatch to project commands, or for file movement, process checks,
+and retry loops. Do not use Bash for business logic or complex text parsing. Do not use it
+for JSON, YAML, XML, or HTML transformations beyond extraction with a dedicated
+parser. Large mutable data structures, long-lived daemons, high-performance work,
+security-sensitive parsing of untrusted input, and behavior that needs typed contracts belong
+elsewhere. A workflow that needs nested maps, large
+arrays, state machines, non-trivial validation, complex retries, concurrent work, or domain
+rules exceeds the scope of a script.
+
+## Deprecated and forbidden syntax
+
+Do not use `function`, `typeset`, `&>`, `|&`, or `for arg; {`. Use `name() { ...; }`,
+`local`, `declare`, `readonly`, explicit redirections, and `for arg in "$@"; do` instead.
+ShellCheck reports `$[ ... ]`, backticks, and `-a` or `-o` inside `[ ... ]`.
+`trap ERR` does not provide general error handling. Check failure where it matters, and reserve traps
+for cleanup that can run safely on the relevant exit path.
+
+## Script structure
+
+<!-- level: all -->
+
+An executable script finishes with a meaningful status: a final diagnostic command, a false
+condition, or an optional cleanup check must not become the script status by accident. Use
+an explicit `exit 0` only when the final command's status differs from the program result and
+prior checks establish success.
+
+## Options
+
+Use `errexit` as a backstop rather than control flow: it has exceptions in
+conditionals, pipelines, command substitutions, subshells, and functions, so `cd`, `rm`,
+check builds, publishing, uploads, and destructive commands explicitly. Do not toggle
+options around a small operation without restoring the prior state. Do not change `IFS` as a
+strict-mode ritual; set it locally where reading or joining data requires it. Keep `set -x`
+out of committed code.
+
+A function called in
+`if`, `while`, `&&`, or `||` writes its checks inside because `errexit` does not stop it there:
+
+```bash
+# cleanup: Removes the contents of the target directory.
+cleanup() {
+  local target="$1"
+
+  cd -- "${target}" || return 1
+  find . -mindepth 1 -maxdepth 1 -exec rm -r -- {} +
+}
+```
+
+Process substitution hides producer failures; when the producer matters, write to a checked
+temporary file, use `PIPESTATUS`, or call the producer separately. Under `pipefail`, short
+readers such as `head` and `grep -q` can make the producer see SIGPIPE and fail the pipeline;
+consume input predictably or handle the known status. Under `nounset`, use `${name:-}` where
+the public interface accepts an unset variable and `${name:?message}` for a required value at a clear
+boundary. Use `${1:-}` where callers can omit an argument.
+
+## Output, logging, and errors
+
+Write diagnostics with `printf`, not `echo`. Return or exit with the intended status: printing
+an error does not make a command fail.
+
+```bash
+# log_status: Prints a timestamped diagnostic line to stderr.
+# Arguments:
+#   Step name.
+#   Target name.
+#   Status label.
+log_status() {
+  local step_name="$1"
+  local target_name="$2"
+  local status_label="$3"
+  local timestamp
+
+  timestamp="$(date -u '+%Y-%m-%dT%H:%M:%SZ')" || return 1
+  printf 'ts=%s script=%s step=%s target=%s status=%s\n' \
+    "${timestamp}" "${0##*/}" "${step_name}" "${target_name}" \
+    "${status_label}" >&2
+}
+```
+
+## Comments and documentation
+
+<!-- level: all -->
+
+A public, sourced, complex, or risky function carries the full header with `Globals`,
+`Arguments`, `Outputs`, and `Returns` sections.