From f42bb8e375ea86cbd2697edee3f830dca54b5b8a Mon Sep 17 00:00:00 2001 From: Claude Date: Thu, 24 Sep 2026 19:12:08 +0000 Subject: [PATCH] docs: route findings away from public issues; add CONTRIBUTING and SECURITY CONTRIBUTING.md carries the rule for where a maintainer's finding goes: the PR description when fixing now, one PR and one tracking issue per QA pass, an internal tracker for CI/test work, and a private advisory for anything security-relevant. SECURITY.md gives that private channel. AGENTS.md and the manual-QA skill point agents at it, since QA passes are where most issue-per-finding batches came from. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01T6sZpGK1T6pcUKy6DNyUaT --- .../skills/hookdeck-cli-manual-qa/SKILL.md | 16 +++++++++ AGENTS.md | 8 +++++ CONTRIBUTING.md | 36 +++++++++++++++++++ SECURITY.md | 29 +++++++++++++++ 4 files changed, 89 insertions(+) create mode 100644 CONTRIBUTING.md create mode 100644 SECURITY.md diff --git a/.agents/skills/hookdeck-cli-manual-qa/SKILL.md b/.agents/skills/hookdeck-cli-manual-qa/SKILL.md index de1b89b6..bf107c2c 100644 --- a/.agents/skills/hookdeck-cli-manual-qa/SKILL.md +++ b/.agents/skills/hookdeck-cli-manual-qa/SKILL.md @@ -298,3 +298,19 @@ what you could not rule out. State plainly what you did **not** cover. A pass that reports only successes is usually a pass that did not go looking. + +### Where findings go + +Report to whoever asked for the pass. **Do not open GitHub issues** unless they +ask you to: the tracker is public, and one pass once produced fourteen issues in +a day, most closed within the hour by the pull requests that fixed them. + +- **Fixing them now:** one branch, one commit per finding, one pull request whose + description carries each finding's five things above. No issues. +- **Deferring some:** one tracking issue with a checklist for the pass, not one + issue per finding. +- **Security-relevant** (a readable credential file, a key or listing in a log, + access to the wrong project): never public. Flag it separately in your report + and point at [SECURITY.md](../../../SECURITY.md). + +The full routing table is in [CONTRIBUTING.md](../../../CONTRIBUTING.md#maintainers-where-a-finding-goes). diff --git a/AGENTS.md b/AGENTS.md index cdf10019..59285ac0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -624,6 +624,14 @@ Each slice's key belongs to a **different project**, which is why tests must use --- +## Issues and findings + +- **Do not open a GitHub issue unless asked to.** The tracker is public. A finding you are fixing belongs in the pull request description; findings from one QA or review pass go in one pull request, and anything deferred in a single tracking issue. +- **Anything security-relevant never goes in a public issue**, pull request title or commit subject that describes the exposure: credentials, file permissions, secrets in logs, access across projects. Say so to whoever asked, and route it to a private advisory ([SECURITY.md](SECURITY.md)). +- Everything else follows **[CONTRIBUTING.md § Maintainers: where a finding goes](CONTRIBUTING.md#maintainers-where-a-finding-goes)**. + +--- + ## Agent skills - **Location:** Repo-specific agent skills live under **`.agents/skills/`** (e.g. `.agents/skills/hookdeck-cli-release/`). This is the cross-harness location: it is not tied to any one tool, so every agent reads the same tree. diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..cb412461 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,36 @@ +# Contributing to the Hookdeck CLI + +## Reporting a bug or asking for a feature + +Open an issue. That is what the issue tracker is for, and a report with the exact +command, its output and what you expected instead is the fastest one to act on. + +If what you found could expose credentials, data or another user's access, do not +open an issue: see [SECURITY.md](SECURITY.md). + +## Opening a pull request + +Pull requests are welcome. [AGENTS.md](AGENTS.md) describes the project layout, +CLI conventions and how to run the tests; it is written for agents but reads as +a contributor guide. + +## Maintainers: where a finding goes + +The issue tracker is public, and it is the first thing someone evaluating the CLI +reads. An issue opened and closed within the hour tells a watcher nothing the pull +request did not, and forty open bugs filed by the maintainers in a week read as +instability rather than diligence. So a finding goes to the narrowest place that +does its job: + +| The finding is | It goes in | +|---|---| +| Being fixed now | The pull request description. No issue. | +| One of several from a single QA or review pass | One branch, one commit per finding, one pull request. Anything deferred goes in a **single** tracking issue with a checklist, not one issue each. | +| A user-visible bug that is not being fixed yet | A public issue: a user who hits it will search for it. | +| Internal only: CI, test flakiness, agent tooling | The team's internal tracker, not this repository. | +| Security-relevant: credentials, file permissions, secrets in logs, access across projects or organisations | A private security advisory ([SECURITY.md](SECURITY.md)). **Never** a public issue or a pull request title that describes the exposure before a release carries the fix. | + +Before opening an issue, search for an existing one; a duplicate costs every +watcher two notifications. + +Agents follow the same table, and do not open issues at all unless asked to. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 00000000..1a59e1d4 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,29 @@ +# Security policy + +## Reporting a vulnerability + +Report it privately through GitHub: +**[Report a vulnerability](https://github.com/hookdeck/hookdeck-cli/security/advisories/new)** +(the repository's **Security** tab → **Report a vulnerability**). + +Do not open a public issue or pull request for it. A public report describes the +exposure to everyone before a release carries the fix. + +Include what you ran, what it exposed, and the CLI version (`hookdeck version`). + +## What counts + +Anything that could expose a credential, project data or access to someone who +should not have it. For this CLI that includes, for example: + +- a config or credential file written with permissions other local users can read +- a key, token or project listing printed to a log, CI output or error message +- a command or MCP tool acting on a project or organisation other than the one + selected + +When unsure, report it privately; it can always be made public afterwards. + +## Supported versions + +Fixes are released on the latest major version. Update with your package manager +(`brew upgrade hookdeck`, `npm install -g hookdeck-cli@latest`, `scoop update hookdeck`).