hatch3r 1.8.0 → 2.0.0

package/dist/content/skills/hatch3r-cli-gh/SKILL.md

@@ -0,0 +1,139 @@
+---
+id: hatch3r-cli-gh
+name: hatch3r-cli-gh
+type: skill
+description: "GitHub CLI — repos, issues, PRs, releases, gists. Use when drafting GitHub pull requests, issues, releases, gists, or workflow dispatches; invoke `gh`. Authenticates via the platform's native token mechanism (OAuth / PAT)."
+tags: ["cli-tools", "forge", "orchestration"]
+quality_charter: agents/shared/quality-charter.md
+efficiency_patterns: agents/shared/efficiency-patterns.md
+cache_friendly: true
+# D9-H-6 (D9, P1): pre-approve the wrapped shell binary on the GitHub Copilot
+# Skills surface so the runtime skips per-invocation confirmation for `gh`.
+# Rendered as an `allowed-tools:` frontmatter line on `.github/skills/.../SKILL.md`
+# by the Copilot adapter; other adapters ignore the field.
+allowed_tools: ["gh"]
+cli_tool:
+  id: gh
+  bin: gh
+  tier: 1
+  category: forge
+  homepage: https://cli.github.com/
+---
+<!-- HATCH3R-CLI-SKILL-GENERATED v1 -->
+# gh
+
+GitHub CLI — repos, issues, PRs, releases, gists
+
+## §0 — Ambiguity & Safety Gate (P8 B1)
+
+Before invoking `gh`, resolve these via `agents/shared/user-question-protocol.md` (default behavior, not exception-driven):
+- **Scope:** when the target repo/PR/issue number is not explicit (e.g. "close the PR" with several open), confirm which one before acting — never guess the number.
+- **Irreversibility:** `gh pr close`, `gh pr merge`, `gh release create`, `gh issue close`, `gh repo delete`, and `gh api -X DELETE/POST/PATCH` mutate remote state. Confirm intent before running any of these; they are not safe to assume.
+- **Ambiguity:** when the request maps to two or more flag combinations with materially different blast radius (e.g. `--squash` vs `--rebase` on `gh pr merge`), ask which one.
+
+## Fan-out Discipline (P8 B2)
+
+Tier 1 reference card — no fan-out. This skill is a single-tool usage reference an agent consults inline; it spawns no sub-agents. Fan-out is owned by the calling workflow per its own Fan-out Discipline block. Source: `rules/hatch3r-fan-out-discipline.md` (P8 B2).
+
+## When to Use
+
+Reach for `gh` when the task is in the **forge** category and the agent would otherwise call an MCP tool or read large outputs into context.
+
+## Token Cost
+
+CLI tools return structured stdout that fits in <1KB for typical queries; equivalent MCP calls regularly exceed 10KB.
+Reference: Anthropic engineering (Nov 4 2025) — code-execution-over-MCP yields 98.7% token reduction.
+
+## Recipes
+
+```bash
+gh pr view 123 --json title,state,body,reviewDecision
+```
+Targeted JSON projection — pulls just the fields the agent needs, not the whole PR payload.
+
+```bash
+gh issue list --label bug --json number,title,author --limit 50
+```
+Label-filtered list with capped page size — avoids paginating the entire issue corpus into context.
+
+```bash
+gh api repos/:owner/:repo/contents/path/to/file.ts --jq '.sha'
+```
+Direct REST passthrough with built-in `--jq` filter — single round-trip, no jq install required at call site.
+
+```bash
+gh run watch
+```
+Blocks until the most recent CI run finishes — pairs with PR creation flows so the agent doesn't poll.
+
+```bash
+gh release create v1.7.5 --notes-from-tag --target release/1.7.5
+```
+Cuts a release using annotated-tag notes; deterministic input avoids hand-edited release bodies.
+
+```bash
+gh pr checks 78 --watch
+```
+Live-tail status checks for a PR — return value reflects the worst check state, scripts can branch on it.
+
+## Wrong Choice When
+
+- Don't reach for `gh` against a GitLab or Azure DevOps remote. Reach for `glab` or `az repos`/`az devops` (both covered in `hatch3r-cli-toolbox` — Forges section).
+- Don't use `gh auth login` flows when an audit trail of who authorized what is required; OAuth scopes granted to the CLI are user-bound. Reach for the GitHub web UI plus org-level SSO logs.
+- Don't use `gh api` for high-volume bulk fetches (>10k records) — rate limits bite. Reach for the GraphQL endpoint via `gh api graphql -F query=@file.gql` with pagination, or a GitHub App token.
+
+## Alternatives
+
+| Tool | When to prefer |
+|------|----------------|
+| `glab` (toolbox section) | GitLab forges — same operations, different vendor. |
+| `az-devops` (toolbox section) | Azure DevOps forges. |
+| `git` + `curl` against REST | Minimal environment (CI runner) where installing `gh` is blocked; trade convenience for raw HTTP. |
+| GitHub web UI | Operations needing org-level approval flows or SAML re-auth that the CLI cannot proxy. |
+
+## Detection / Install
+
+Verify with:
+```bash
+command -v gh
+```
+
+Install (macOS — default for this machine):
+
+```bash
+# brew
+brew install gh
+```
+
+Install (Linux):
+
+```bash
+# apt
+sudo apt install gh
+```
+
+Install (Windows):
+
+```bash
+# winget
+winget install GitHub.cli
+```
+
+Homepage: https://cli.github.com/
+
+## Security
+
+Minimum recommended version: `>=2.93.0`. Builds below this floor carry known unpatched advisories — upgrade before relying on the tool.
+
+GHSA-8xvp-7hj6-mcj9 (CVE-2026-48501, High): gh CLI 2.92.0 and earlier attach the Authorization header to TUF repository-mirror requests issued by `gh attestation`, `gh release verify`, and `gh release verify-asset` — sending the github.com token (or `GH_ENTERPRISE_TOKEN` / `GITHUB_ENTERPRISE_TOKEN`) to hosts that are not GitHub API endpoints (`tuf-repo.github.com`, `tuf-repo-cdn.sigstore.dev`, and an Azure blob host). Any token previously used with those commands should be treated as exposed and rotated. Fixed in 2.93.0 — upgrade before running attestation or release-verify flows.
+
+GHSA-crc3-h8v6-qh57 (CVE-2026-45803, Low): `gh run view --log` and `gh run view --log-failed` stream GitHub Actions workflow log lines to stdout or the pager without sanitizing terminal control sequences, so a malicious workflow can embed escape sequences that execute when a maintainer views the log (altered window titles, manipulated output, command execution in emulators such as `screen`). This is an escape-sequence-injection issue, not a token leak. Fixed in 2.92.0 — upgrade before viewing logs from untrusted workflows.
+
+GHSA-55v3-xh23-96gh (token-leak note, `cli/go-gh` library): inside a codespace, `auth.TokenForHost` could source `GITHUB_TOKEN` for a non-`github.com`/`ghe.com` host, sending the token to an unintended host. Fixed in go-gh 2.11.1, vendored into gh ≥ 2.42.0; the `>=2.93.0` floor already clears it. Relevant when running gh against untrusted GitHub Enterprise hosts from a codespace.
+
+## References
+
+- GHSA-8xvp-7hj6-mcj9 / CVE-2026-48501 — https://github.com/cli/cli/security/advisories/GHSA-8xvp-7hj6-mcj9 (accessed 2026-06-06; tier: vendor advisory — GitHub CLI maintainers)
+- GHSA-crc3-h8v6-qh57 / CVE-2026-45803 — https://github.com/cli/cli/security/advisories/GHSA-crc3-h8v6-qh57 (accessed 2026-06-05; tier: vendor advisory — GitHub CLI maintainers)
+- GHSA-55v3-xh23-96gh — https://github.com/cli/go-gh/security/advisories/GHSA-55v3-xh23-96gh (accessed 2026-06-05; tier: vendor advisory — GitHub CLI maintainers)
+- GitHub Advisory Database (queried via `gh api /repos/cli/cli/security-advisories`, accessed 2026-06-05; tier: official advisory feed)

package/{skills → dist/content/skills}/hatch3r-cli-jq/SKILL.md

@@ -1,10 +1,17 @@
 ---
 id: hatch3r-cli-jq
+name: hatch3r-cli-jq
+type: skill
 description: "JSON processor and query language. Use when shaping JSON streams via jq-syntax filters and select expressions; invoke `jq`. Reads stdin and emits stdout; integrates seamlessly into shell pipelines."
-tags: ["cli-tools", "json", "core"]
+tags: ["cli-tools", "json", "orchestration"]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
+# D9-H-6 (D9, P1): pre-approve the wrapped shell binary on the GitHub Copilot
+# Skills surface so the runtime skips per-invocation confirmation for `jq`.
+# Rendered as an `allowed-tools:` frontmatter line on `.github/skills/.../SKILL.md`
+# by the Copilot adapter; other adapters ignore the field.
+allowed_tools: ["jq"]
 cli_tool:
   id: jq
   bin: jq
@@ -17,6 +24,17 @@ cli_tool:
 
 JSON processor and query language
 
+## §0 — Ambiguity & Safety Gate (P8 B1)
+
+Before invoking `jq`, resolve these via `agents/shared/user-question-protocol.md` (default behavior, not exception-driven):
+- **Scope:** when the input JSON path is ambiguous (a glob like `*.json` or a slurp over several shards), confirm which files feed the filter before running.
+- **Irreversibility:** `jq` reads stdin and writes stdout, so it is non-destructive by itself — but redirecting its output over the source (`jq … input.json > input.json`) truncates the file before `jq` reads it. Write to a temp file and rename, never redirect over the input.
+- **Ambiguity:** when the request maps to two or more filter expressions with materially different output shape (raw `-r` vs JSON, `select` vs `map`), ask which one.
+
+## Fan-out Discipline (P8 B2)
+
+Tier 1 reference card — no fan-out. This skill is a single-tool usage reference an agent consults inline; it spawns no sub-agents. Fan-out is owned by the calling workflow per its own Fan-out Discipline block. Source: `rules/hatch3r-fan-out-discipline.md` (P8 B2).
+
 ## When to Use
 
 Reach for `jq` when the task is in the **json** category and the agent would otherwise call an MCP tool or read large outputs into context.
@@ -56,22 +74,18 @@ Compact (`-c`) one-object-per-line projection — perfect input for `xargs -L1`
 ## Wrong Choice When
 
 - Don't use `jq` for bidirectional grep on flattened paths; the inverse (`gron` outputs `obj.foo.bar = …` lines you can `rg` then translate back). Reach for `gron`.
-- Don't use `jq` directly on multi-document YAML or front-matter Markdown. Reach for `yq` (`hatch3r-cli-yq`) and pipe `yq -o=json` into `jq` only if you need jq's filter language.
+- Don't use `jq` directly on multi-document YAML or front-matter Markdown. Reach for `yq` (toolbox section in `hatch3r-cli-toolbox`) and pipe `yq -o=json` into `jq` only if you need jq's filter language.
 - Don't reach for `jq` when the file is a stream of newline-delimited JSON (`.ndjson`); use `jq -c` per line or `jaq`/`fx` for stream-friendly behavior — `jq` without `-c` slurps the whole file.
 
 ## Alternatives
 
 | Tool | When to prefer |
 |------|----------------|
-| `yq` (`hatch3r-cli-yq`) | YAML, TOML, XML input — yq speaks them all, jq is JSON-only. |
+| `yq` (toolbox section) | YAML, TOML, XML input — yq speaks them all, jq is JSON-only. |
 | `gron` | Flatten JSON to `path = value` lines for grep-based exploration and reverse-translation. |
-| `dasel` | Single binary across JSON/YAML/TOML/XML with a path-query DSL — handy in CI where you do not want jq+yq. |
+| `dasel` | Single binary across JSON/YAML/TOML/XML with a path-query DSL — handy in CI where you do not want jq+yq. Pin to >=3.11.0 (clears CVE-2026-33320 fixed in 3.3.2, plus CVE-2026-46377 / -46378 fixed in 3.10.1). |
 | `fx` | Interactive JSON browsing in a TTY; jq is the right call in scripts. |
 
-## Known Issues
-
-- **CVE-2026-32316 (active, no tagged fix as of 2026-05-18):** jq 1.8.1 ships with a heap buffer overflow in expression evaluation. Six additional CVEs were disclosed 2026-04-15; patches are committed on `jqlang/jq` `main` but no superseding tagged release exists yet. Do not invoke `jq` on JSON sourced from an untrusted producer (third-party API webhook, user-supplied upload) until a tagged release past 1.8.1 lands. Reference: https://github.com/jqlang/jq/security/advisories.
-
 ## Detection / Install
 
 Verify with:
@@ -79,11 +93,31 @@ Verify with:
 command -v jq
 ```
 
-Install (mac):
+Install (macOS — default for this machine):
 
 ```bash
 # brew
 brew install jq
 ```
 
+Install (Linux):
+
+```bash
+# apt
+sudo apt install jq
+```
+
+Install (Windows):
+
+```bash
+# scoop
+scoop install jq
+```
+
 Homepage: https://github.com/jqlang/jq
+
+## Security
+
+Minimum recommended version: `>=1.8.1`. Builds below this floor carry known unpatched advisories — upgrade before relying on the tool.
+
+Multiple unfixed advisories on jq 1.8.1 (the only tagged release as of 2026-05-27). See https://github.com/jqlang/jq/security/advisories for the canonical roster — at audit time the upstream tab listed 10+ GHSA entries (April-May 2026), all stack-overflow / integer-overflow / NUL-truncation classes triggerable by attacker-controlled JSON or attacker-controlled jq filter paths. Validate JSON inputs externally (e.g. python json.tool or jaq) or sandbox jq in a network-isolated container before running on untrusted input.

package/{skills → dist/content/skills}/hatch3r-cli-ripgrep/SKILL.md

@@ -1,10 +1,17 @@
 ---
 id: hatch3r-cli-ripgrep
+name: hatch3r-cli-ripgrep
+type: skill
 description: "Fast recursive grep with sane defaults and gitignore awareness. Use when regex content searches across large source trees with gitignore filtering; invoke `rg`. Outputs newline-separated hit records; bound results with `-c` or `--max-count`."
-tags: ["cli-tools", "search", "core"]
+tags: ["cli-tools", "search", "orchestration"]
 quality_charter: agents/shared/quality-charter.md
 efficiency_patterns: agents/shared/efficiency-patterns.md
 cache_friendly: true
+# D9-H-6 (D9, P1): pre-approve the wrapped shell binary on the GitHub Copilot
+# Skills surface so the runtime skips per-invocation confirmation for `rg`.
+# Rendered as an `allowed-tools:` frontmatter line on `.github/skills/.../SKILL.md`
+# by the Copilot adapter; other adapters ignore the field.
+allowed_tools: ["rg"]
 cli_tool:
   id: ripgrep
   bin: rg
@@ -17,6 +24,17 @@ cli_tool:
 
 Fast recursive grep with sane defaults and gitignore awareness
 
+## §0 — Ambiguity & Safety Gate (P8 B1)
+
+Before invoking `rg`, resolve these via `agents/shared/user-question-protocol.md` (default behavior, not exception-driven):
+- **Scope:** when the search root is ambiguous or the request implies piercing ignore rules (`--no-ignore`, `--hidden`) over a large tree, confirm the intended path before running — an unscoped scan over a monorepo can return tens of thousands of hits.
+- **Irreversibility:** `rg` is read-only — it never mutates files, so no destructive confirmation is needed. The only risk is unbounded output flooding context; cap with `--max-count` / `-l` / `-c` when match density is unknown.
+- **Ambiguity:** when the request maps to two or more pattern interpretations (literal `-F` vs regex, case-sensitive vs `-i`), ask which one.
+
+## Fan-out Discipline (P8 B2)
+
+Tier 1 reference card — no fan-out. This skill is a single-tool usage reference an agent consults inline; it spawns no sub-agents. Fan-out is owned by the calling workflow per its own Fan-out Discipline block. Source: `rules/hatch3r-fan-out-discipline.md` (P8 B2).
+
 ## When to Use
 
 Reach for `rg` when the task is in the **search** category and the agent would otherwise call an MCP tool or read large outputs into context.
@@ -55,7 +73,7 @@ Two-phase: file list first, then ranged scan — keeps stdout small when match d
 
 ## Wrong Choice When
 
-- Don't use `rg` to match by code structure (function calls, type signatures, JSX shape); literal regex misses renames and whitespace variants. Reach for `ast-grep` (`hatch3r-cli-ast-grep`).
+- Don't use `rg` to match by code structure (function calls, type signatures, JSX shape); literal regex misses renames and whitespace variants. Reach for `ast-grep` (see the ast-grep section in `hatch3r-cli-toolbox`).
 - Don't run `rg` against binary blobs (`.zst`, `.png`, lockfile snapshots); it skips them silently by default but explicit `-a` mode wastes CPU. Reach for category-specific tools (`zstd -d` then `rg`, or `xxd | rg` for hex).
 - Don't use `rg` to search a specific git revision or stash — it only sees the working tree. Reach for `git grep <rev>`.
 
@@ -63,7 +81,7 @@ Two-phase: file list first, then ranged scan — keeps stdout small when match d
 
 | Tool | When to prefer |
 |------|----------------|
-| `ast-grep` (`hatch3r-cli-ast-grep`) | Structural code patterns: matchers like `console.log($MSG)` that survive whitespace and identifier renames. |
+| `ast-grep` (toolbox section) | Structural code patterns: matchers like `console.log($MSG)` that survive whitespace and identifier renames. |
 | `git grep` | Search at a specific revision, tag, or stash — `rg` only reads the working tree. |
 | `fd` (`hatch3r-cli-fd`) piped into `rg` | Filename pre-filter when scoping by extension/age is faster than `rg --type`. |
 | `grep -RIn` | POSIX-only environment where ripgrep is not on PATH and install is blocked. |
@@ -75,11 +93,25 @@ Verify with:
 command -v rg
 ```
 
-Install (mac):
+Install (macOS — default for this machine):
 
 ```bash
 # brew
 brew install ripgrep
 ```
 
+Install (Linux):
+
+```bash
+# apt
+sudo apt install ripgrep
+```
+
+Install (Windows):
+
+```bash
+# scoop
+scoop install ripgrep
+```
+
 Homepage: https://github.com/BurntSushi/ripgrep