@gspothq/cli 0.1.1 → 0.2.0

package/configurations/general/spelling/manifest.toml

@@ -1,46 +1,36 @@
 [configuration]
-title = "Spelling"
 always_selected = true
-description = "typos over every text file, with the words this repository allows and the reason for each."
+description = "Runs typos over every text file, with the allowed words and a reason for each."
+title = "Spelling"
 
 [files]
 paths = ["**"]
 
 [[tool]]
-name = "typos"
-version = "1.43.5"
-mise = "typos"
 brew = "typos-cli"
 cargo = "typos-cli"
-winget = "crate-ci.typos"
-scoop = "typos"
 github = { name = "crate-ci/typos", version = "v1.43.5" }
-[[tool.replace]]
-file = "typos.toml"
-shared = false
-
-[[tool.replace]]
-file = ".typos.toml"
-shared = false
-
-[[tool.replace]]
-file = "_typos.toml"
-shared = false
+mise = "typos"
+name = "typos"
+replace = ["typos.toml", ".typos.toml", "_typos.toml"]
+scoop = "typos"
+version = "1.43.5"
+winget = "crate-ci.typos"
 
 [[tool_file]]
+per_scope = true
 target = ".gspot/config/typos.toml"
 tool = "typos"
-per_scope = true
 
 [[check]]
-name = "typos"
-example = "A misspelled word in selected text reports a spelling finding. Correct it and rerun. Filename findings require a manual rename and reference updates."
-level = "recommended"
-stage = "commit"
 command = ["typos", "--isolated", "--config", "{tool_file:typos}", "--force-exclude", "--format", "json", "--color", "never", "{files}"]
-fix = ["typos", "--isolated", "--config", "{tool_file:typos}", "--force-exclude", "--no-check-filenames", "--write-changes", "--color", "never", "{files}"]
+example = "A misspelled word reports a finding. Correct it, and for a file name, rename the file and update each reference to it."
 exit_codes = [2]
+fix = ["typos", "--isolated", "--config", "{tool_file:typos}", "--force-exclude", "--no-check-filenames", "--write-changes", "--color", "never", "{files}"]
+help = "Fix the spelling, or write the real name and its reason in the root allowed_words setting."
+level = "recommended"
+name = "typos"
 output = { format = "typos" }
+stage = "commit"
 summary = "Finds misspelled words in code, comments, and documentation."
 why = "A typo in an identifier spreads to every caller; in prose it costs the reader a second look."
-help = "Fix the spelling, or write the real name and its reason in the root allowed_words setting."

package/configurations/general/structure/manifest.toml

@@ -1,70 +1,70 @@
 [configuration]
-title = "Structure"
 always_selected = true
-description = "The structural rules no standard linter ships, over every language: wrappers, barrels, lone files, and the size limits."
+description = "Structural rules that no standard linter ships, for every language: wrappers, barrels, lone files, and size limits."
+title = "Structure"
 
 [files]
 languages = true
 
 [[check]]
+example = "With TypeScript at level `all`, a `feature/only.ts` alone in its folder reports `lone-file`. Move it up beside related code, and update its imports."
+help = "Move the file up beside its neighbors, or use `gspot ignore structure/lone-files` with paths and a reason."
+level = "all"
 name = "lone-files"
-example = "With the TypeScript configuration at level `all`, `feature/only.ts` reports `lone-file` when it is the folder's only code file. Move it beside related files and update references, or keep the folder when a second substantial file belongs to that feature. Adding `feature/second.ts` makes this folder contain two code files."
 runs = "scope"
-level = "all"
 stage = "commit"
 summary = "Finds a folder that holds one code file and nothing else."
-why = "A folder of one file adds a level to every path and promises siblings that never arrive."
-help = "Move the file up beside its neighbors, or use gspot ignore structure/lone-files with paths and a reason."
+why = "A folder with one file adds a level to every import path and groups nothing."
 
 [[check]]
-name = "shared-prefixes"
 example = "Sibling files `asset-card.ts`, `asset-list.ts`, and `asset-row.ts` share a repeated prefix. Move them into `asset/` with names `card.ts`, `list.ts`, and `row.ts`, then update imports."
-runs = "scope"
+help = "Move the files into a folder named after the shared prefix, or allow the set with a reason."
 level = "all"
+name = "shared-prefixes"
+runs = "scope"
 stage = "commit"
-summary = "Finds sibling files that share a name prefix, like asset-card, asset-list and asset-row in one folder."
-why = "Files that share a prefix are one concept split by suffix; they belong in a folder named after the prefix."
-help = "Move the files into a folder named after the shared prefix, or allow the set with a reason."
+summary = "Finds sibling files that share a name prefix, such as `asset-card`, `asset-list`, and `asset-row`."
+why = "Sibling files with one prefix split a single concept by suffix, and a folder of that name groups them."
 
 [[check]]
+example = "A `report.ts` beside a `report/` folder reports a clash. Rename one after its job, and update each reference."
+help = "Rename the file or the folder so their stems differ."
+level = "all"
 name = "file-folder-clashes"
-example = "Sibling entries `report.ts` and `report/` have the same stem and report a collision. Rename the file or directory after its distinct responsibility and update every reference."
 runs = "scope"
-level = "all"
 stage = "commit"
-summary = "Finds a file and a folder in the same place with the same stem, like turn.ts beside turn/."
+summary = "Finds a file and a folder with one stem in the same place, such as `turn.ts` beside `turn/`."
 why = "An import of ./turn names both, and a reader cannot tell which one loads."
-help = "Rename the file or the folder so their stems differ."
 
 [[check]]
-name = "file-lines"
-example = "A Python, Bash, or SQL source file above its language's code-line ceiling reports its count. Split independent responsibilities into their owners and rerun the check."
+example = "A Python file over its line limit reports the count. Split it by responsibility."
+files = { extensions = [".sh", ".bash", ".zsh", ".bats", ".py", ".pyi", ".sql", ".pgsql", ".psql"], tags = ["shebang:shell"], kinds = ["source"] }
+help = "Split the file by responsibility, or raise limits.`<language>`.file_lines with a reason."
 level = "all"
-stage = "commit"
+name = "long-files"
 runs = "scope"
-files = { extensions = [".sh", ".bash", ".zsh", ".bats", ".py", ".pyi", ".sql", ".pgsql", ".psql"], tags = ["shebang:shell"], kinds = ["source"] }
-summary = "Checks source code lines against each language's ceiling."
+stage = "commit"
+summary = "Checks the code line count of each file against the limit for its language."
 why = "A long file hides independent responsibilities from the reader."
-help = "Split the file by its responsibility, or raise its limits.`<language>`.file_lines with a reason."
 
 [[check]]
-name = "trivial-functions"
-example = "A Bash function that only calls another function reports its declaration. Inline that call into its callers and remove the forwarding function."
+example = "A Bash function that only calls another reports a finding. Inline the call at each caller, and delete the wrapper."
+files = { extensions = [".ts", ".tsx", ".js", ".mjs", ".cjs", ".py", ".swift", ".sh", ".bash", ".zsh", ".bats"], tags = ["shell"], kinds = ["source"] }
+help = "Inline a forwarding function at its calls and delete it. Split independent statements into the files that use them."
 level = "all"
-stage = "commit"
+name = "trivial-functions"
 runs = "scope"
-files = { extensions = [".py", ".swift", ".sh", ".bash", ".zsh", ".bats"], tags = ["shell"], kinds = ["source"] }
+stage = "commit"
 summary = "Finds functions with too few statements and files that only forward to other code."
 why = "A function of one statement makes the reader jump for nothing."
-help = "Inline a forwarding function at its calls and delete it. Split independent statements into the files that use them."
 
 [[check]]
-name = "env-reads"
-example = "A Python file outside architecture.roles.environment_readers that reads os.environ reports that read. Move it into a declared environment reader and pass its value to callers."
+example = "A Python file that uses `os.environ` outside `architecture.roles.environment_readers` reports a finding. Move that access into an environment reader, and pass the value to callers."
+files = { extensions = [".py", ".swift", ".sh", ".bash", ".zsh", ".bats"], tags = ["shell"], kinds = ["source"] }
+help = "Move the environment read into a file listed in architecture.roles.environment_readers, then pass the value to callers."
 level = "all"
-stage = "commit"
+name = "environment-readers"
 runs = "scope"
-files = { extensions = [".py", ".swift", ".sh", ".bash", ".zsh", ".bats"], tags = ["shell"], kinds = ["source"] }
+stage = "commit"
 summary = "Finds environment reads outside the files listed in architecture.roles.environment_readers."
 why = "Environment reads spread through the code hide which settings a program needs."
-help = "Move the environment read into a file listed in architecture.roles.environment_readers, then pass the value to callers."

package/configurations/infrastructure/ansible/manifest.toml

@@ -1,33 +1,33 @@
 [configuration]
-title = "Ansible"
 description = "Ansible playbooks, roles, and collections checked by ansible-lint."
+title = "Ansible"
 
 [files]
 paths = ["**/ansible.cfg", "**/galaxy.yml", "**/requirements.yml", "**/roles/*/tasks/main.yml"]
 
 [[tool]]
-name = "ansible-lint"
-version = "26.8.0"
-min_version = "24.0.0"
-pypi = "ansible-lint"
-mise = "pipx:ansible-lint"
 brew = "ansible-lint"
 builds = ["macos", "linux"]
+min_version = "24.0.0"
+mise = "pipx:ansible-lint"
+name = "ansible-lint"
+pypi = "ansible-lint"
+version = "26.8.0"
 
 [[tool_file]]
+per_scope = true
 target = ".gspot/config/ansible-lint.yml"
 tool = "ansible-lint"
-per_scope = true
 
 [[check]]
-name = "ansible-lint"
-example = "A task using `ansible.builtin.command: systemctl restart nginx` reports `command-instead-of-module`. Use `ansible.builtin.systemd` with `name: nginx` and `state: restarted` to express the intended service operation."
+command = ["ansible-lint", "-c", "{tool_file:ansible-lint}", "--offline", "--nocolor", "-f", "pep8", "--profile", "{level:moderate:production}"]
+example = "A task with `ansible.builtin.command: systemctl restart nginx` reports `command-instead-of-module`. Use `ansible.builtin.systemd` with `name: nginx` and `state: restarted` instead."
+files = { extensions = [".yml", ".yaml", ".cfg", ".j2"] }
+help = "Change the task the way the rule says. Turn one rule off with `gspot ignore ansible/ansible-lint --rule <id> --reason \"<why>\"`."
 level = "recommended"
-stage = "commit"
+name = "ansible-lint"
 runs = "scope"
+stage = "commit"
+summary = "Runs the moderate ansible-lint profile at recommended and production at all, beside each ansible.cfg or at the scope root."
 tool = "ansible-lint"
-command = ["ansible-lint", "-c", "{tool_file:ansible-lint}", "--offline", "--nocolor", "-f", "pep8", "--profile", "{level:moderate:production}"]
-files = { extensions = [".yml", ".yaml", ".cfg", ".j2"] }
-summary = "Runs the moderate ansible-lint profile at recommended and production at all, beside each ansible.cfg or at the selected scope root."
-why = "A playbook runs as root on production hosts, and a task that is not idempotent changes them on every run."
-help = "Change the task the way the rule says. Turn one rule off with gspot ignore ansible/ansible-lint --rule `<id>` --reason \"`<why>`\"."
+why = "Playbooks run as root on production hosts, and a non-idempotent task changes them each time."

package/configurations/infrastructure/docker/manifest.toml

@@ -1,9 +1,8 @@
-prefix_collisions = { prefixes = ["docker"] }
-
 allowed_words = ["Docker", "Trivy"]
+
 [configuration]
+description = "Dockerfiles and Compose files: hadolint, Compose parsing, a `.dockerignore` beside each Dockerfile, and Trivy scans."
 title = "Docker"
-description = "Dockerfiles and Compose files: hadolint, a Compose file that parses, an ignore file beside every Dockerfile, and Trivy over the configuration."
 
 [detect]
 paths = ["**/Dockerfile", "**/Dockerfile.*", "**/*.dockerfile", "**/docker-compose*.yml", "**/docker-compose*.yaml", "**/compose*.yml", "**/compose*.yaml", "!**/*.dockerignore"]
@@ -11,117 +10,106 @@ paths = ["**/Dockerfile", "**/Dockerfile.*", "**/*.dockerfile", "**/docker-compo
 [files]
 paths = ["**/Dockerfile", "**/Dockerfile.*", "**/*.dockerfile", "**/docker-compose*.yml", "**/docker-compose*.yaml", "**/compose*.yml", "**/compose*.yaml", "**/.dockerignore", "**/*.dockerignore"]
 
+[shared_prefixes]
+prefixes = ["docker"]
+
 [[tool]]
-name = "hadolint"
-version = "2.14.0"
-mise = "hadolint"
 brew = "hadolint"
 github = { name = "hadolint/hadolint", version = "v2.14.0" }
+mise = "hadolint"
+name = "hadolint"
+replace = [".hadolint.yaml", ".hadolint.yml"]
 scoop = "hadolint"
-[[tool.replace]]
-file = ".hadolint.yaml"
-shared = false
-
-[[tool.replace]]
-file = ".hadolint.yml"
-shared = false
+version = "2.14.0"
 
 [[tool]]
-name = "trivy"
-version = "0.69.3"
-mise = "trivy"
 brew = "trivy"
 github = { name = "aquasecurity/trivy", version = "v0.69.3" }
-[[tool.replace]]
-file = "trivy.yaml"
-shared = false
-
-[[tool.replace]]
-file = ".trivyignore"
-shared = false
+mise = "trivy"
+name = "trivy"
+replace = ["trivy.yaml", ".trivyignore"]
+version = "0.69.3"
 
 [[tool]]
-name = "docker"
 install_hint = "install Docker Desktop or the docker engine"
+name = "docker"
 system = true
 
 [[tool_file]]
+per_scope = true
 target = ".gspot/config/hadolint.yml"
 tool = "hadolint"
-per_scope = true
-rule_keys = ["ignored"]
 
 [[tool_file]]
+per_scope = true
 target = ".gspot/config/trivy.yml"
 tool = "trivy"
-per_scope = true
 
 [[tool_file]]
-source = "trivyignore"
+per_scope = true
 target = ".gspot/config/trivyignore"
 tool = "trivy"
-per_scope = true
 
 [[check]]
-name = "hadolint"
-example = "The instruction `FROM node:latest` reports DL3007 because the tag changes over time. Select a reviewed, explicit version tag or digest and rerun."
-level = "recommended"
-stage = "commit"
 command = ["hadolint", "--no-color", "--config", "{tool_file:hadolint}", "{files}"]
+example = "`FROM node:latest` reports DL3007, because that tag moves. Pin an explicit version tag or a digest."
 files = { paths = ["**/Dockerfile", "**/Dockerfile.*", "**/*.dockerfile", "!**/*.dockerignore"] }
+help = "Change the instruction the way the rule says. Turn one rule off with `gspot ignore docker/hadolint --rule <id> --reason \"<why>\"`."
+level = "recommended"
+name = "hadolint"
 output = { format = "regex", pattern = "^(?<file>.+?):(?<line>\\d+) (?<rule>[A-Z]+\\d+) [a-z]+: (?<message>.*)$" }
+stage = "commit"
 summary = "Lints every Dockerfile, and runs ShellCheck over its RUN lines."
-why = "An unpinned base image or a cache left in a layer makes a build nobody can repeat and an image larger than it needs to be."
-help = "Change the instruction the way the rule says. Turn one rule off with gspot ignore docker/hadolint --rule `<id>` --reason \"`<why>`\"."
+why = "An unpinned base image makes a build nobody can repeat, and a cache left in a layer bloats the result."
 
 [[check]]
-name = "compose"
-example = "A Compose service with an unknown key such as `bogus` fails configuration validation. Remove the key or replace it with the supported setting for the intended behavior."
-level = "recommended"
-stage = "push"
-needs = ["docker"]
-tool = "docker"
-runs = "scope"
 command = ["docker", "compose", "-f", "{file}", "config", "--quiet", "--no-env-resolution"]
+example = "A Compose service with the unknown key `bogus` fails to parse. Remove the key, or use a supported one."
 files = { paths = ["**/docker-compose*.yml", "**/docker-compose*.yaml", "**/compose*.yml", "**/compose*.yaml"] }
-output = { format = "lines" }
-summary = "Asks Docker Compose to parse every Compose file, which needs no running daemon."
-why = "A Compose file that is valid YAML can still name a key Compose refuses, and the first person to learn that is deploying."
 help = "Read the message Compose prints; it names the key and the service."
+level = "recommended"
+name = "compose"
+needs = ["docker"]
+output = { format = "lines" }
+runs = "scope"
+stage = "push"
+summary = "Parses every Compose file with `docker compose config`, which needs no running daemon."
+tool = "docker"
+why = "Valid YAML can still hold a key that Compose rejects, and otherwise the first sign comes during a deploy."
 
 [[check]]
-name = "dockerignore"
-example = "A Dockerfile without a neighboring `.dockerignore` reports the missing context exclusions. Add `.dockerignore` with the required entries named in the finding, such as `.git` and dependency directories."
+example = "A Dockerfile with no `.dockerignore` beside it reports a finding. Add one that excludes the paths the finding names, such as `.git` and installed dependencies."
+help = "Add a .dockerignore beside the Dockerfile with the paths the message names."
 level = "recommended"
-stage = "commit"
+name = "dockerignore"
 runs = "once"
-summary = "Checks that an ignore file sits beside every Dockerfile and keeps the git folder, installed dependencies, and environment files out of the build."
-why = "Without it the whole folder goes to the daemon, and copying the folder puts the history and the secrets into the image."
-help = "Add a .dockerignore beside the Dockerfile with the entries the message names."
+stage = "commit"
+summary = "Checks that an ignore file sits beside every Dockerfile and keeps the `.git` folder, installed dependencies, and environment files out of the build."
+why = "Without it, the daemon receives the whole folder, and a `COPY` of it puts the history and secrets into the image."
 
 [[check]]
-name = "trivy-config"
-example = "A Dockerfile whose final application stage runs as root can report a container-security finding. Create an unprivileged user, grant it only required file access, and select it with `USER` before running the application."
-level = "recommended"
-stage = "push"
-runs = "scope"
-run_in_copy = true
 command = ["trivy", "config", "--misconfig-scanners", "dockerfile", "--quiet", "--skip-check-update", "--config", "{tool_file:trivy}", "--ignorefile", "{tool_file:trivyignore}", "--exit-code", "10", "--format", "sarif", "{root}"]
-tool = "trivy"
+example = "A Dockerfile whose final stage runs as root reports a finding. Create an unprivileged user, and switch to it with `USER` before the application starts."
 exit_codes = [10]
+help = "Change the file the way the message says. Accept one advisory with `gspot ignore docker/trivy-config --rule <id> --reason \"...\"`."
+level = "recommended"
+name = "trivy-config"
 output = { format = "sarif" }
+run_in_copy = true
+runs = "scope"
+stage = "push"
 summary = "Scans Dockerfiles for HIGH and CRITICAL misconfigurations, including a root user and exposed secrets."
-why = "A container that runs as root turns any bug in the service into control of the container."
-help = "Change the file the way the message says. Accept one advisory with gspot ignore docker/trivy-config --rule `<id>` --reason \"...\"."
+tool = "trivy"
+why = "A root user turns any bug in the service into full control of the container."
 
 [[check]]
-name = "trivy-image"
-example = "A configured image containing a package with a known advisory reports that advisory. Move to a reviewed image version containing the package fix, then rerun the image scan. Results depend on the advisory database and available image."
+example = "An image with a vulnerable package reports the advisory. Move to an image version with the fixed package."
+help = "Move to a newer tag of the image. Accept one advisory with `gspot ignore docker/trivy-image --rule <id> --reason \"...\"`."
 level = "recommended"
-stage = "manual"
-runs = "scope"
+name = "trivy-image"
 needs = ["docker"]
-tool = "trivy"
+runs = "scope"
+stage = "manual"
 summary = "Scans every image a Compose file names for known vulnerabilities in its packages."
-why = "A base image carries hundreds of packages, and their advisories arrive after the image was chosen."
-help = "Move to a newer tag of the image. Accept one advisory with gspot ignore docker/trivy-image --rule `<id>` --reason \"...\"."
+tool = "trivy"
+why = "A base image carries hundreds of packages, and new advisories keep arriving after you pick it."

package/configurations/infrastructure/docker/rules/DOCKER.md

@@ -1,12 +1,14 @@
 # Docker
 
+Read this rule when you change a Dockerfile, a Compose file, or `.dockerignore`.
+
 ## Image inputs
 
-Select a base image that supports the application's runtime, target architecture, native libraries,
+Select a base image that supports the application's runtime, target architecture, system libraries,
 and certificate requirements. Tags can change, so pin a reviewed digest when the build requires
 immutable input, and keep an update process for security fixes: a digest never patches itself.
 
-Use a supported runtime release. For native modules, keep the build and runtime operating system,
+Use a supported runtime release. For compiled modules, keep the build and runtime operating system,
 libc, and architecture compatible. Alpine, Debian, and distroless images have different runtime
 and operational requirements; no single variant fits every application.
 
@@ -48,7 +50,7 @@ CMD ["node", "dist/main.js"]
 Use the package manager the project declares; for Bun, its pinned version with
 `bun install --frozen-lockfile`, adding `--production` for runtime dependencies. The final image
 holds a package-manager binary only when the runtime uses it. A statically linked `server` built
-for the target platform needs no package manager or shell, only the certificates, time-zone data,
+for the target system needs no package manager or shell, only the certificates, time-zone data,
 or other runtime files it reads.
 
 ```dockerfile
@@ -61,11 +63,11 @@ ENTRYPOINT ["/server"]
 ## Package installation and downloads
 
 hadolint reports unpinned images and packages, apt cleanup, `ADD` for local files, and shell-form
-commands. Review these additional requirements:
+commands. Also apply these requirements:
 
 - Install application dependencies from the declared lockfile without updating it during the build.
-- Refresh repository metadata and install packages in the same `RUN`, so cached metadata cannot
-  select an unintended version.
+- Refresh repository metadata and install packages in the same `RUN`, so a stale cache cannot
+  pick an unintended version.
 - Refresh base images for operating-system fixes. A targeted package upgrade needs an explicit
   dependency change, never an unbounded distribution upgrade in every build.
 - Verify a downloaded executable's digest or signature before installing it.
@@ -77,7 +79,7 @@ commands. Review these additional requirements:
 
 Put stable build inputs before frequently changing application source when that improves cache
 reuse. Put substantial shell behavior in an existing script. Keep the final image's user,
-working directory, environment, and startup command in documented locations. Do not add a wrapper script
+working folder, environment, and startup command in documented locations. Do not add a wrapper script
 for a command the container can run directly.
 
 ## Build context and ignore files
@@ -92,11 +94,11 @@ Dockerfile that uses it. A deny-by-default context suits a small, stable input s
 
 Use BuildKit secret mounts for private registry authentication and other build credentials.
 Read the secret only inside the `RUN` instruction that requires it. Copying it into a layer keeps
-it in image history even if a later layer removes it.
+it in image history even after a later step removes it.
 
 ## Shell and process behavior
 
-Use the shell syntax actually selected for `RUN`; the default shell does not run Bash. A required
+Match `RUN` syntax to the configured shell; the default one does not run Bash. A required
 entrypoint script validates configuration and uses `exec` for its final handoff. A documented
 process supervisor forwards signals and reaps its children, and no init wrapper hides missing
 shutdown behavior in the application.
@@ -110,9 +112,9 @@ The application's shutdown limit fits the orchestrator's grace period.
   service sets `NODE_ENV=production` where the runtime expects it.
 - Expose only the required ports, and bind private local services to localhost. Never add Linux
   capabilities, public debug ports, or disabled TLS verification to make a build or service work.
-- Resource limits fit the deployment and leave room for native memory, buffers, and runtime
-  overhead beyond a language heap limit. Ask the user for memory measurements before changing a limit
-  when the task provides none.
+- Resource limits fit the deployment and leave room for off-heap memory, buffers, and runtime
+  overhead beyond the language heap. Ask the user for memory measurements before changing a limit
+  when the task has none.
 
 ## Compose
 
@@ -123,7 +125,7 @@ development source or host dependencies.
 
 ## Verification
 
-Do not build or run images unless the user asks or the repository's checks require it. Give the user a list of items to check: the image's user, command, runtime files, permissions, exposed ports, startup,
+Do not build or run images unless the user asks or the repository's checks require it. Give the user a checklist: image user, command, runtime files, permissions, exposed ports, startup,
 readiness, shutdown, and resource limits. Image documentation names the current build arguments,
 supported platforms, runtime environment, and artifact paths.
 

package/configurations/infrastructure/github-actions/manifest.toml

@@ -1,76 +1,56 @@
 allowed_words = ["GitHub"]
+
 [configuration]
+description = "GitHub Actions workflows: actionlint for syntax and expressions, and zizmor for security audits and action pins."
 title = "GitHub Actions"
-description = "GitHub Actions workflows: actionlint for syntax and expressions, pinact for the commits actions are pinned to, and zizmor for security audits."
 
 [files]
 paths = ["**/.github/workflows/*.{yml,yaml}", "**/action.{yml,yaml}"]
 
 [[tool]]
-name = "actionlint"
-version = "1.7.12"
-mise = "actionlint"
 brew = "actionlint"
 github = { name = "rhysd/actionlint", version = "v1.7.12" }
+mise = "actionlint"
+name = "actionlint"
+version = "1.7.12"
 
 [[tool]]
 name = "shellcheck"
 
 [[tool]]
-name = "pinact"
-crash_pattern = '(?:ERROR|FATAL).*?(?:\b(?:401|403|408|429|5[0-9]{2})\b|dial tcp|TLS handshake|x509:|context deadline exceeded|connection reset|no such host)'
-version = "5.0.0"
-mise = "pinact"
-brew = "pinact"
-github = { name = "suzuki-shunsuke/pinact", version = "v5.0.0" }
-
-[[tool]]
-name = "zizmor"
-version = "1.30.1"
-mise = "zizmor"
-pypi = "zizmor"
 brew = "zizmor"
 cargo = "zizmor"
+mise = "zizmor"
+name = "zizmor"
+pypi = "zizmor"
+version = "1.30.1"
 
 [[tool_file]]
-source = "zizmor.yml"
 target = ".gspot/config/zizmor.yml"
 tool = "zizmor"
 
 [[check]]
-name = "actionlint"
-example = "A workflow using an unknown expression context such as `${{ unknown.value }}` reports an actionlint error. Replace it with a supported context and property for that workflow location."
-level = "recommended"
-stage = "commit"
-tool = ["actionlint", "shellcheck"]
 command = ["actionlint", "-no-color", "{files}"]
-files = { paths = ["**/.github/workflows/*.{yml,yaml}"] }
+example = "A workflow expression with the unknown context `${{ unknown.value }}` reports an error. Use a supported context and property there instead."
 exit_codes = [1]
+files = { paths = ["**/.github/workflows/*.{yml,yaml}"] }
+help = "Fix the line actionlint names."
+level = "recommended"
+name = "actionlint"
 output = { format = "regex", pattern = "^(?<file>[^:]+):(?<line>\\d+):(?<column>\\d+): (?<message>.*?) \\[(?<rule>[a-z-]+)\\]$" }
+stage = "commit"
 summary = "Checks every GitHub Actions workflow with actionlint: syntax, expressions, action inputs, and shell steps."
+tool = ["actionlint", "shellcheck"]
 why = "A workflow error surfaces on the first push after the change, in CI, where it costs a round trip."
-help = "Fix the line actionlint names."
 
 [[check]]
-name = "pinact"
-example = "An action reference such as `actions/checkout@v4` without a full commit pin reports an unpinned action. Resolve a reviewed release to its full commit SHA and record the matching version comment beside the pin."
-level = "recommended"
-stage = "push"
-needs = ["network"]
-command = ["pinact", "run", "--verify-comment", "--check", "{files}"]
-output = { format = "lines" }
-summary = "Checks that each GitHub action has a full commit pin that exists and a matching version comment."
-why = "A tag can move between runs, a nonexistent commit prevents the workflow from starting, and a wrong version comment hides the intended release."
-help = "Replace the invalid action pin with a verified commit and its matching version comment."
-
-[[check]]
-name = "zizmor"
-example = "A workflow interpolating pull-request text directly into a shell command can report a template-injection audit. Pass the text through a step environment variable and quote its expansion instead of interpolating it into shell code."
-level = "recommended"
-stage = "commit"
 command = ["zizmor", "--offline", "--no-progress", "--format", "github", "--config", "{tool_file:zizmor}", "{files}"]
+example = "A workflow that puts pull request text straight into a shell command reports `template-injection`. Pass the text through a step environment variable, and quote its expansion."
 exit_codes = [11, 12, 13, 14]
+help = "Apply the fix zizmor names, or turn one audit off with `gspot ignore github-actions/zizmor --rule <audit> --reason \"<why>\"`."
+level = "recommended"
+name = "zizmor"
 output = { format = "regex", pattern = "^::(?:warning|error|notice) file=(?<file>[^,]+),line=(?<line>\\d+),title=(?<rule>[^:]+)::(?<message>.*)$" }
+stage = "commit"
 summary = "Audits GitHub Actions workflows and composite actions with zizmor for template injection, excessive permissions, and dangerous triggers."
 why = "A workflow runs with the repository's credentials; an injectable expression can hand them to a stranger."
-help = "Apply the fix zizmor names, or turn one audit off with gspot ignore github-actions/zizmor --rule `<audit>` --reason \"`<why>`\"."

package/configurations/infrastructure/github-actions/rules/GITHUB-ACTIONS.md

@@ -1,13 +1,17 @@
 # GitHub Actions
 
+Read this rule when you change a GitHub Actions workflow or action.
+
 ## Workflow shape
 
-- Every job has `timeout-minutes`. Every workflow that can run twice for one ref has a
-  `concurrency` group with `cancel-in-progress` for pull requests.
+- Every job has `timeout-minutes`.
+- Every workflow that can run twice for one ref has a `concurrency` group. Cancel a run in progress only for a pull
+  request. Never cancel a run on the default branch or a tag; its result records that commit.
 - Pin a runner image such as `ubuntu-24.04` for each job. Do not use `ubuntu-latest`.
-- No `continue-on-error` without a reason comment. Required failures must fail the job.
-- Upload diagnostics after failed checks with an explicit status condition. Deployments and
-  release publication require successful prerequisites.
+- No `continue-on-error` without a reason comment. Required steps that break must fail the job.
+- Upload diagnostics after failed checks with an explicit status condition. Deployments and release publication
+  require successful prerequisites.
+- Before a release job publishes a package or creates a release, it runs the tests or needs the job that does.
 
 ## Repository actions and secrets
 
@@ -17,19 +21,19 @@
 
 ## Scripts
 
-- Declare the shell required by the script. The explicit Bash shell in GitHub Actions enables `-e` and
-  `pipefail`, but does not enable `-u`. Enable required options and validate inputs explicitly.
+- Declare the shell required by the script. The explicit Bash shell in GitHub Actions turns on `-e` and
+  `pipefail`, but not `-u`. Enable required options and validate inputs explicitly.
 - Key caches on the lockfile hash and the runtime version. Restore keys never match a
   different lockfile.
 
 ## Outputs
 
 - Artifacts and summaries name the job and the ref. Set retention explicitly.
-- Give deploy credentials only to the workflow that deploys. Run it on a protected
-  environment with a reviewer.
-
-See [the GitHub shell configuration](https://docs.github.com/en/actions/reference/workflows-and-actions/workflow-syntax#jobsjob_idstepsshell)
-for the command each runner uses.
+- Each job leaves a result that a later one, a deployment, or a person uses. Do not upload an artifact that no job
+  downloads. Do not build the same output in two workflows.
+- Give deploy credentials only to the job that deploys, as `env` on the step that needs them. Deploy only from the
+  default branch or a release tag. When the repository uses GitHub environments, run the job in a protected
+  one with a reviewer.
 
 ## Workflow organization