diff --git a/.github/cursor-approve/README.md b/.github/cursor-approve/README.md index cd986a83..1a43af3c 100644 --- a/.github/cursor-approve/README.md +++ b/.github/cursor-approve/README.md @@ -65,7 +65,8 @@ Tests: `python3 -m unittest discover -s .github/cursor-approve/tests -p 'test_*. ## `context-proxy.py` A read-only stdio MCP server that gives the business, design and completeness -axes Linear, Notion and Slack context without the agent ever holding a token. +axes Linear and Notion context without the agent ever holding a token. It still +implements Slack tools, but the base workflow refuses `slack`: no axis reads it. It reads a token file once, deletes it, and sends every request through one guard function that allow-lists each read endpoint before anything goes out. diff --git a/.github/cursor-approve/tests/test_context_axes.py b/.github/cursor-approve/tests/test_context_axes.py index 27af259a..a3ace0c1 100644 --- a/.github/cursor-approve/tests/test_context_axes.py +++ b/.github/cursor-approve/tests/test_context_axes.py @@ -10,8 +10,10 @@ TOKENS = ("LINEAR_KEY", "NOTION_TOKEN", "SLACK_TOKEN") AXES = { - "business": {"secrets": ["CURSOR_API_KEY", "LINEAR_KEY", "NOTION_TOKEN", "SLACK_TOKEN"], - "checkout": "false", "no_shell": "true", "sources": "linear,notion,slack"}, + # `declared` adds secrets a wrapper accepts for compatibility but never uses. + "business": {"secrets": ["CURSOR_API_KEY", "LINEAR_KEY", "NOTION_TOKEN"], + "declared": ["CURSOR_API_KEY", "LINEAR_KEY", "NOTION_TOKEN", "SLACK_TOKEN"], + "checkout": "false", "no_shell": "true", "sources": "linear,notion"}, "design": {"secrets": ["CURSOR_API_KEY", "LINEAR_KEY", "NOTION_TOKEN"], "checkout": "false", "no_shell": "true", "sources": "linear,notion"}, "completeness": {"secrets": ["CURSOR_API_KEY", "LINEAR_KEY"], @@ -55,10 +57,19 @@ def test_each_wrapper_declares_exactly_its_secrets(self): text = read(f"axis-{axis}.yml") on_call = block(text, "workflow_call:", 2) secrets = block("\n".join(on_call), "secrets:", 4) - self.assertEqual(keys(secrets, 6), want["secrets"], axis) + self.assertEqual(keys(secrets, 6), want.get("declared", want["secrets"]), axis) self.assertEqual(set(re.findall(r"secrets\.([A-Za-z_]+)", text)), set(want["secrets"]), axis) self.assertNotIn("secrets: inherit", text, axis) + def test_no_wrapper_enables_slack(self): + for axis in AXES: + sources = re.search(r"context_sources: *(\S*)", read(f"axis-{axis}.yml")).group(1) + self.assertNotIn("slack", sources.split(","), axis) + + def test_base_rejects_slack(self): + base = read("cursor-axis-base.yml") + self.assertIn('*,slack,*) echo "::error::context_sources may not include slack', base) + def test_checkout_no_shell_and_sources(self): for axis, want in AXES.items(): text = read(f"axis-{axis}.yml") diff --git a/.github/workflows/axis-business.yml b/.github/workflows/axis-business.yml index 9ee59309..7435995a 100644 --- a/.github/workflows/axis-business.yml +++ b/.github/workflows/axis-business.yml @@ -3,14 +3,17 @@ name: Cursor axis (business) # The business axis of cursor-approve: a thin wrapper over cursor-axis-base.yml. # No checkout and no shell: the agent sees the PR title, body and # changed-file list with line counts, fetched by the workflow. -# Company context comes through context-proxy.py (tools: linear,notion,slack), which -# holds the tokens; the agent never does. Declares ONLY the secrets below, all +# Company context comes through context-proxy.py (tools: linear,notion), which +# holds the tokens; the agent never does. No Slack: it is where people debate +# before deciding, not a record of the decision, and anyone can post in it, so +# it is neither evidence of business intent nor safe to feed an approver. Declares ONLY the secrets below, all # but CURSOR_API_KEY optional (a missing token leaves that tool unconfigured). # Runs only on same-repo PRs in a PRIVATE repo; otherwise it skips with a # notice. See docs/callers/cursor-approve.md for the caller and accepted risk. # # Inputs (passed through): commit_sha, model, runs_on. -# Secrets: CURSOR_API_KEY, LINEAR_KEY, NOTION_TOKEN, SLACK_TOKEN. +# Secrets: CURSOR_API_KEY, LINEAR_KEY, NOTION_TOKEN. SLACK_TOKEN is still declared, +# and ignored, so a caller that passes it is not rejected at startup. on: workflow_call: @@ -31,6 +34,8 @@ on: required: false NOTION_TOKEN: required: false + # Deprecated and unused: never forwarded. Kept so an existing caller's + # `SLACK_TOKEN:` line does not fail its whole workflow file. SLACK_TOKEN: required: false @@ -55,7 +60,7 @@ jobs: axis: business checkout: false no_shell: true - context_sources: linear,notion,slack + context_sources: linear,notion commit_sha: ${{ inputs.commit_sha }} model: ${{ inputs.model }} runs_on: ${{ inputs.runs_on }} @@ -63,4 +68,3 @@ jobs: CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }} LINEAR_KEY: ${{ secrets.LINEAR_KEY }} NOTION_TOKEN: ${{ secrets.NOTION_TOKEN }} - SLACK_TOKEN: ${{ secrets.SLACK_TOKEN }} diff --git a/.github/workflows/cursor-axis-base.yml b/.github/workflows/cursor-axis-base.yml index 913ee840..6d8e33e1 100644 --- a/.github/workflows/cursor-axis-base.yml +++ b/.github/workflows/cursor-axis-base.yml @@ -123,6 +123,12 @@ jobs: if ! [[ "$CONTEXT_SOURCES" =~ ^((linear|notion|slack)(,(linear|notion|slack))*)?$ ]]; then echo "::error::context_sources must be a comma list of linear, notion, slack"; exit 1 fi + # No axis reads Slack (docs/callers/cursor-approve.md, "Context + # axes"): enforced here, not only in the wrappers, so a direct caller + # of this public base cannot turn it back on. + case ",$CONTEXT_SOURCES," in + *,slack,*) echo "::error::context_sources may not include slack: no axis reads Slack"; exit 1 ;; + esac if [ -n "$CONTEXT_SOURCES" ]; then case "$AXIS" in business|design|completeness) ;; diff --git a/README.md b/README.md index 09defcb6..eeaa5158 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ complete, copy-pasteable caller. | [`detect-unreviewed-merge.yml`](.github/workflows/detect-unreviewed-merge.yml) | SOC 2 compliance — detects PRs merged without prior approval and opens a tracking issue in [`Comfy-Org/unreviewed-merges`](https://github.com/Comfy-Org/unreviewed-merges). | [detect-unreviewed-merge.md](docs/callers/detect-unreviewed-merge.md) | | [`linear-ticket.yml`](.github/workflows/linear-ticket.yml) | **Requires a Linear issue that Linear has LINKED to the exact PR when the PR targets a protected base branch** — not a `TEAM-123`-shaped string in author text. The validator reads GitHub's branch `protected` property, so any number of branches protected by branch protection or rulesets are covered without a caller-maintained list; unprotected targets publish no `Linear ticket` status and do not query Linear (a success status would be unsafe because GitHub scopes statuses to a SHA, not a PR). For protected targets, the only thing that passes is an attachment Linear returns for the PR's canonical `html_url` (`attachmentsForURL`, PR URL passed as a GraphQL **variable**) whose issue satisfies the configured team (`team-keys`, matched on the resolved API `team.key`, never a prefix) and state (`require-open-issue` rejects `completed`/`canceled` via `state.type`) policy; a PR linked to several tickets passes when at least one satisfies policy. Identifiers mined from branch/title/body are **diagnostics only** (capped at 20, one batched lookup) — they explain a red check, never turn it green. Fork- and Dependabot-safe by a two-stage split: an unprivileged, checks-out-nothing **signal** workflow on `pull_request`, then a privileged validator on `workflow_run` that GitHub grants the secret + write token. It publishes the required **`Linear ticket`** commit status on the refetched PR head SHA (its own default-branch job is *not* the merge check), refetches the head SHA and base branch before every terminal write so a superseded or retargeted run can't overwrite a newer result, maintains one marker diagnostic comment, and **fails closed** on unreadable branch protection or Linear auth/schema/timeout/rate-limit errors (an infrastructure failure, never a green pass) with bounded retry for Linear's async-link race. `enforce: false` is warn-only — a failing verdict never exits the job nonzero (a broken run still does), and by default (`soft-fail: true`) it still publishes the **red** status so the pilot is visible on the PR while blocking nothing, since blocking is branch protection requiring the context, not this workflow's call (`soft-fail: false` restores the silent always-green variant); one `exempt-label` (e.g. `linear-exempt`) waives it per-PR, and an opt-in `exempt-actors` list (empty by default) skips bot PRs (e.g. `dependabot[bot]`) with no built-in bypass. An opt-in `exempt-paths` list exempts a PR whose changed files **all** match (config-only chores arriving from many different authors); it is decided IN the validator — reading the GitHub-owned changed-file list, failing closed past that endpoint's silent 3000-file cap — precisely so an exempt PR still publishes the green required status, which a `paths-ignore:` on the signal workflow could not (an unpublished required context leaves the PR pending forever). Logic + hermetic tests live in [`scripts/linear-ticket/`](scripts/linear-ticket); `workflows_ref` is **required**, shape- and ancestry-checked before checkout. Requires `LINEAR_API_TOKEN` + the two-workflow caller. | [linear-ticket.md](docs/callers/linear-ticket.md) | | [`cursor-review.yml`](.github/workflows/cursor-review.yml) | Label-triggered multi-model code review. A 3-lab × 2-review-type cursor-agent panel runs adversarial + edge-case passes, a judge model consolidates them into one PR review with per-finding severity badges, and the triggerer gets Slack start/complete DMs. Advisory by default: it posts a review, it does not gate. Opt-in `blocking: true` adds a fail-closed **Blocking gate** check — red while any finding thread is unresolved and non-outdated, and red whenever the round that should have produced those threads did not land (the trigger job failed, the post exited zero without reaching the PR, every finding was demoted to the review body, the diff was over `diff_size_cap`, or the run was cancelled) — which blocks merge once the caller's ruleset marks it required (two switches; see [the setup guide](docs/callers/cursor-review.md)). Separately and **always on**, a **Panel integrity** check reports whether the panel that reviewed the PR was a *whole* panel — red when fewer reviewer cells submitted than ran, when findings could not be anchored to the diff and were demoted to the review body, when no review carrying resolvable threads reached the PR, when the judge never adjudicated, or when the jobs that decide whether to review at all did not succeed (an undecided run is not a clean run). It takes no input and gates nothing by itself; ` / Panel integrity` is the stable context to mark required if you want completeness gated — **not** an individual panel leg, whose name carries the model id and changes whenever the pins move. Two consequences to read before bumping onto it: a cell that does not submit now fails its own leg instead of exiting green, so **your caller job goes red** on a measured ~40% of runs (that red is the signal — the consolidated review still posts, and the Blocking gate is unaffected); and the deliberate no-panel branches leave it *skipped*, which a required check counts as passing, so a skip answers "no panel was warranted", never "the panel was fine". Scope and limits — including forgeability and same-SHA supersession — are in [the setup guide](docs/callers/cursor-review.md). Prompts and scripts live in [`.github/cursor-review/`](.github/cursor-review) — the single source of truth, so consumer repos carry only a thin caller. Generated code is excluded from BOTH the diff-size gate and the diff sent to the panel via the shared [`check-pr-size`](scripts/check-pr-size) classifier (base-ref `linguist-generated`, base-blob Go generated markers — a PR cannot self-exempt a file from review, lockfiles, plus `extra_generated_globs` / `extra_lockfiles`) — the same detection as `pr-size.yml`, so codegen never blows the review cap or wastes review signal. Blank and comment-only lines are also discounted from the size count by default (`ignore_comments`) so AI comment volume doesn't trip the cap and skip the review — comments still reach the panel, only the count ignores them. The panel model list is fixed by the reusable — there is no `models` input (`models` is a job *output*); an optional `runs_on` routes only the credential-free heavy jobs (`diff-size`, `preflight`, panel, judge) to a caller's runner pool, while every write-credential job stays on GitHub-hosted `ubuntu-latest`. Least privilege by construction: no job both checks out PR code and holds a write-scoped credential — every job that checks out PR code and runs `cursor-agent` over it (every panel cell and the judge) holds `contents: read` only, and hands its result to a separate, checkout-free `Post review` job via an artifact; that job and the over-the-cap comment job are the only holders of `pull-requests: write`, and neither checks out PR code. Requires `CURSOR_API_KEY` (+ optional `SLACK_BOT_TOKEN`). | [cursor-review.md](docs/callers/cursor-review.md) | -| [`cursor-approve.yml`](.github/workflows/cursor-approve.yml) + [`axis-correctness.yml`](.github/workflows/axis-correctness.yml) / [`axis-conformance.yml`](.github/workflows/axis-conformance.yml) / [`axis-business.yml`](.github/workflows/axis-business.yml) / [`axis-design.yml`](.github/workflows/axis-design.yml) / [`axis-completeness.yml`](.github/workflows/axis-completeness.yml) | Per-axis approval after a passing cursor-review round (`approve_gate == 'pass'`). Each axis is its own reusable declaring only the secrets it needs (correctness/conformance: `CURSOR_API_KEY` only; business/design/completeness add optional read-only Linear/Notion/Slack tokens, held by a local read-only MCP proxy the agent never sees the tokens of, private repos only), runs one read-only `cursor-agent` judgement over the PR head via the shared [`cursor-axis-base.yml`](.github/workflows/cursor-axis-base.yml), and uploads one verdict artifact. `cursor-approve.yml`, called with `phase: start` and `phase: decide`, keeps one live status card on the PR and approves through `auto-approve.py approve-external` (head re-read, reviewed-SHA marker, own stale approvals withdrawn, never over `needs-human-review` or `skip-cursor-review`, both re-read live). Prompts and the aggregator live in [`.github/cursor-approve/`](.github/cursor-approve). Requires `CURSOR_API_KEY` + `APPROVER_TOKEN`. | [cursor-approve.md](docs/callers/cursor-approve.md) | +| [`cursor-approve.yml`](.github/workflows/cursor-approve.yml) + [`axis-correctness.yml`](.github/workflows/axis-correctness.yml) / [`axis-conformance.yml`](.github/workflows/axis-conformance.yml) / [`axis-business.yml`](.github/workflows/axis-business.yml) / [`axis-design.yml`](.github/workflows/axis-design.yml) / [`axis-completeness.yml`](.github/workflows/axis-completeness.yml) | Per-axis approval after a passing cursor-review round (`approve_gate == 'pass'`). Each axis is its own reusable declaring only the secrets it needs (correctness/conformance: `CURSOR_API_KEY` only; business/design/completeness add optional read-only Linear/Notion tokens, held by a local read-only MCP proxy the agent never sees the tokens of, private repos only), runs one read-only `cursor-agent` judgement over the PR head via the shared [`cursor-axis-base.yml`](.github/workflows/cursor-axis-base.yml), and uploads one verdict artifact. `cursor-approve.yml`, called with `phase: start` and `phase: decide`, keeps one live status card on the PR and approves through `auto-approve.py approve-external` (head re-read, reviewed-SHA marker, own stale approvals withdrawn, never over `needs-human-review` or `skip-cursor-review`, both re-read live). Prompts and the aggregator live in [`.github/cursor-approve/`](.github/cursor-approve). Requires `CURSOR_API_KEY` + `APPROVER_TOKEN`. | [cursor-approve.md](docs/callers/cursor-approve.md) | | [`cursor-review-auto-label.yml`](.github/workflows/cursor-review-auto-label.yml) | Companion to `cursor-review.yml`. On PR assignment, applies the review label for an opted-in reviewer (via the CLOUD_CODE_BOT app token, so the label actually triggers the review). The opt-in roster lives in the caller's `vars.CURSOR_REVIEW_OPTED_IN_LOGINS` — no roster is baked into the workflow. Requires `vars.APP_ID` + `CLOUD_CODE_BOT_PRIVATE_KEY`, or the optional `bot_app_id` + `BOT_APP_PRIVATE_KEY` pair to mint from a narrower App instead. | [cursor-review-auto-label.md](docs/callers/cursor-review-auto-label.md) | | [`assign-reviewers.yml`](.github/workflows/assign-reviewers.yml) | Assigns PR owners using configured paths and recent human approval history. Chooses complementary file coverage before workload, with an explained one-owner default fallback and no random substitutions. Optionally generates a shared history artifact on schedule/manual dispatch and reuses fresh snapshots across PRs. Reads configuration from the base SHA, respects manual assignments, and preserves opt-in `REVIEWER_AUTHOR_ALLOWLIST` scoping. Requires `vars.APP_ID` + `CLOUD_CODE_BOT_PRIVATE_KEY`; callers skip forks and Dependabot triggers. | [assign-reviewers.md](docs/callers/assign-reviewers.md) | | [`assign-prs-to-author.yml`](.github/workflows/assign-prs-to-author.yml) | Housekeeping — assigns every open PR with no assignees to its author (bot-authored PRs skipped by default). Run on a schedule from a thin caller; useful when a team tracks PR ownership via assignees. The calling job needs `pull-requests: write` and `issues: write`. | [assign-prs-to-author.md](docs/callers/assign-prs-to-author.md) | diff --git a/docs/callers/cursor-approve.md b/docs/callers/cursor-approve.md index b64eae77..20c1975c 100644 --- a/docs/callers/cursor-approve.md +++ b/docs/callers/cursor-approve.md @@ -355,21 +355,28 @@ JSON (`verdict`, `confidence`, `summary` capped at 1200 characters) reaches ## Context axes `axis-business.yml`, `axis-design.yml` and `axis-completeness.yml` judge a PR -against company context, not just its code. They read Linear, Notion and Slack +against company context, not just its code. They read Linear and Notion through `.github/cursor-approve/context-proxy.py`, a read-only MCP server that holds the tokens: the agent can search, but never holds a credential. +No axis reads Slack. Slack is where people debate before they decide, not a +record of what was decided: the decision lands in a ticket, a PRD or a TDD. +Treating a thread as evidence that a change was wanted rewards opening a thread +to get a PR approved, and anyone in a channel can post the text an approver +then reads. The proxy still implements `slack_search` / `slack_history`, but +`cursor-axis-base.yml` rejects `slack` in `context_sources`, so no caller can +enable them. `axis-business.yml` still declares an optional `SLACK_TOKEN` that it +never forwards, so a caller that passes one keeps working; drop the line when +convenient. + | Axis | Agent sees | Context tools | Secrets (all but `CURSOR_API_KEY` optional) | |---|---|---|---| -| business | PR title, body, changed-file list with line counts — no checkout, no shell | `linear_search`, `linear_get_issue`, `notion_search`, `notion_get_page`, `slack_search`, `slack_history` | `CURSOR_API_KEY`, `LINEAR_KEY`, `NOTION_TOKEN`, `SLACK_TOKEN` | +| business | PR title, body, changed-file list with line counts — no checkout, no shell | `linear_search`, `linear_get_issue`, `notion_search`, `notion_get_page` | `CURSOR_API_KEY`, `LINEAR_KEY`, `NOTION_TOKEN` | | design | PR title, body, merge-base diff cut at 200 KB — no checkout, no shell | `linear_search`, `linear_get_issue`, `notion_search`, `notion_get_page` | `CURSOR_API_KEY`, `LINEAR_KEY`, `NOTION_TOKEN` | | completeness | Full read-only checkout (`persist-credentials: false`), shell allowed for `git` | `linear_search`, `linear_get_issue` | `CURSOR_API_KEY`, `LINEAR_KEY` | A missing token leaves that source unconfigured; the axis still runs. The tokens -are read-only bot identities (Linear and Notion as the tools bot, Slack as the -cursor-approver app). The Slack bot cannot call `search.messages`, so the proxy -loads the last 30 days of every public channel the bot is a member of and -searches that. +are read-only bot identities (Linear and Notion as the tools bot). How a token reaches the proxy without reaching the agent: @@ -402,7 +409,6 @@ Business and design fetch the change from the GitHub compare API, which CURSOR_API_KEY: ${{ secrets.CURSOR_API_KEY }} LINEAR_KEY: ${{ secrets.LINEAR_KEY }} NOTION_TOKEN: ${{ secrets.NOTION_TOKEN }} - SLACK_TOKEN: ${{ secrets.SLACK_TOKEN }} axis-design: needs: [cursor-review, approve-start]