Skip to content

Worktrunk is a CLI for Git worktree management, designed for parallel AI agent workflows

chore: trim .github/CLAUDE.md, remove local security model (#2011)

Maximilian Roos1134ca8128b5
diff --git a/.github/CLAUDE.md b/.github/CLAUDE.md
index b30c48c99..8f6a5b8df 100644
--- a/.github/CLAUDE.md
+++ b/.github/CLAUDE.md
@@ -1,91 +1,30 @@
-# CI Automation Security Model — Worktrunk
+# CI Automation — Worktrunk
-See [tend-security-model.md](tend-security-model.md) for the generic security model
-(security layers, token management, prompt injection, event types, workflow
-modification rules). This file documents worktrunk-specific configuration.
+See [tend's security model](https://github.com/max-sixty/tend/blob/main/docs/security-model.md)
+for the generic security model. This file documents worktrunk-specific
+configuration.
## Bot identity
-`worktrunk-bot` is a regular GitHub user account (PAT-based), not a GitHub App.
+`worktrunk-bot` — a regular GitHub user account (PAT-based, not a GitHub App).
Workflows check `user.login == 'worktrunk-bot'` directly.
## Tokens
-| Token | Used by |
+| Token | Purpose |
|-------|---------|
-| `WORKTRUNK_BOT_TOKEN` | All Claude workflows — consistent identity (`worktrunk-bot`) |
-| `CLAUDE_CODE_OAUTH_TOKEN` | All — authenticates Claude Code to the Anthropic API |
+| `WORKTRUNK_BOT_TOKEN` | All Claude workflows — consistent bot identity |
+| `CLAUDE_CODE_OAUTH_TOKEN` | Authenticates Claude Code to the Anthropic API |
## Merge restriction
-### Ruleset: "Merge access"
-
-- **Rule**: Restrict updates — only bypass actors can push to or merge into `main`
-- **Bypass**: Repository Admin role → **exempt** mode (silent, no checkbox)
-
-`worktrunk-bot` has `write` role (`admin: false`, `maintain: false`). Only the
-repo owner (`@max-sixty`, admin) can merge. GitHub treats merging a PR as a push
-to the base branch, so restricting updates blocks both direct pushes and PR
-merges.
-
-The "exempt" bypass mode silently skips the rule for the admin — no "bypass
-branch protections" checkbox.
-
-### Classic branch protection
-
-- **Required reviews**: none (the ruleset is the merge restriction)
-- **Required status checks**: `test (linux)`, `test (macos)`, `test (windows)`
-- **Enforce admins**: off
-
-**Why not CODEOWNERS?** Deadlock for solo maintainers: the code owner can't
-approve their own PRs. The "Restrict updates" ruleset is simpler: one rule, one
-bypass actor, CI remains enforced for everyone.
-
-**Why not "Restrict who can push"?** Only available for org-owned repos. This
-is a personal repo (`max-sixty/worktrunk`).
+Only the repo owner (`@max-sixty`, admin) can merge to `main`.
+`worktrunk-bot` has `write` role only. Enforced by a "Merge access" ruleset
+(restrict updates, admin bypass in exempt mode). Required status checks:
+`test (linux)`, `test (macos)`, `test (windows)`.
## Environment protection
`CARGO_REGISTRY_TOKEN` and `AUR_SSH_PRIVATE_KEY` are in a protected GitHub
-Environment (`release`) requiring deployment approval from `@max-sixty`. The
-environment has a deployment branch policy restricting to `v*` tags.
-
-## Triage ↔ mention handoff
-
-New issues are always handled by `tend-triage` — `tend-mention` only
-triggers on issue **edits** (not opens) to avoid two workflows racing to create
-fix PRs for the same bug.
-
-- **New issue** (opened) → triage, regardless of `@worktrunk-bot` mentions
-- **Issue edited** to add `@worktrunk-bot` → mention
-- **Comment** on an issue/PR → mention (via `issue_comment` trigger)
-
-The mention workflow runs for any user who includes `@worktrunk-bot` — the merge
-restriction is the safety boundary, not access control on the workflow.
-
-## Bot-engaged auto-response
-
-**Triggers a response:**
-- Non-draft PR opened or updated → automatic code review (`tend-review`)
-- Formal review submitted on a `worktrunk-bot`-authored PR, with body or non-approval → `tend-review` responds
-- `@worktrunk-bot` mentioned in a new issue body → `tend-triage` handles it
-- `@worktrunk-bot` mentioned via issue edit → `tend-mention` responds
-- `@worktrunk-bot` mentioned in any comment → `tend-mention` responds
-- Comment on a PR/issue where `worktrunk-bot` has engaged → `tend-mention` runs, responds only if helpful
-- Editing a comment or issue body re-triggers the mention workflow
-
-**Does not trigger:**
-- `worktrunk-bot`'s own comments (workflow-level loop prevention)
-- Empty approvals on `worktrunk-bot` PRs
-- Comments on issues/PRs where `worktrunk-bot` hasn't engaged and no mention
-- Draft PRs
-
-**Loop prevention for bot reviews:** Bot-authored reviews and review comments
-are no longer filtered at the workflow level (removed in tend#168 to allow the
-bot to apply its own review suggestions). Instead, the prompt includes
-self-conversation loop prevention: the bot exits silently unless there is a
-distinct role boundary (e.g., reviewer on its own PR).
-
-**Routing:** Formal reviews (`pull_request_review`) → `tend-review`. Inline
-comments (`pull_request_review_comment`) and conversation comments
-(`issue_comment`) → `tend-mention`.
+Environment (`release`) requiring deployment approval from `@max-sixty`,
+restricted to `v*` tags.
diff --git a/.github/tend-security-model.md b/.github/tend-security-model.md
deleted file mode 100644
index 89d0b0114..000000000
--- a/.github/tend-security-model.md
+++ /dev/null
@@ -1,150 +0,0 @@
-# CI Automation Security Model
-
-Generic security model for Claude-powered CI workflows. This document covers
-the principles; each adopting repo should document its specific configuration
-(admin accounts, token names, protected environments) in its own `.github/CLAUDE.md`.
-
-## Security layers
-
-Two layers protect a repository, in order of importance:
-
-1. **Merge restriction** — only designated admins can merge to the default
- branch, enforced by a ruleset or branch protection. The bot has write access
- (not admin) and cannot merge regardless of review status.
-2. **Environment protection** — release secrets (registry tokens, signing keys)
- are in a protected GitHub Environment requiring deployment approval,
- preventing exfiltration via modified workflows.
-
-Token scoping (principle of least privilege) is a secondary practice, not a
-security boundary.
-
-## What each workflow needs to do
-
-| Capability | Triage | Mention | Review | CI Fix | Nightly | Renovate |
-|------------|:---:|:---:|:---:|:---:|:---:|:---:|
-| Read issues/PRs | Yes | Yes | Yes | Yes | Yes | — |
-| Comment on issues | Yes | Yes | Yes | — | Yes | — |
-| Create branches | Yes | Yes | Yes | Yes | Yes | Yes |
-| Push commits | Yes | Yes | Yes | Yes | Yes | Yes |
-| Create PRs | Yes | Yes | — | Yes | Yes | Yes |
-| Post PR reviews | — | — | Yes | — | — | — |
-| Resolve review threads | — | — | Yes | — | — | — |
-| Monitor CI | Yes | Yes | Yes | Yes | Yes | Yes |
-| **Pushes must trigger CI** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** | **Yes** |
-
-The last row matters: `GITHUB_TOKEN` pushes don't trigger downstream workflows
-(GitHub prevents infinite loops). Workflows that push code and need CI to run
-**must** use a PAT or GitHub App installation token.
-
-## Token assignment
-
-Use a single bot token across all Claude workflows for consistent identity.
-The merge restriction (ruleset) caps blast radius regardless of which token
-is used.
-
-Two tokens are needed:
-
-| Token | Purpose |
-|-------|---------|
-| Bot token (PAT or App) | GitHub API and git operations. Consistent bot identity. |
-| Claude OAuth token | Authenticates Claude Code to the Anthropic API. |
-
-### Why one bot token
-
-The bot token is equally safe in any workflow because the merge restriction
-caps the blast radius. Using a single token gives consistent identity for
-reviews and comments and avoids the `github-actions[bot]` branding.
-
-### If a token leaks
-
-| Token | Lifetime | If leaked, attacker can... | ...but cannot |
-|-------|----------|---------------------------|---------------|
-| Bot token (PAT) | Long-lived | Push to unprotected branches, create PRs, impersonate bot — **indefinitely** | Merge PRs (merge restriction), push to default branch, access release secrets (environment-protected) |
-| Bot token (App) | ~1 hour | Same as PAT, but only until token expires | Same + token auto-expires |
-| Claude OAuth | Long-lived | Run Claude sessions billed to the account | Access GitHub |
-
-`GITHUB_TOKEN` is ephemeral (single job) and automatically scoped by each
-workflow's `permissions:` block. Not a meaningful leak target.
-
-**Bot token is the high-value target.** Mitigations:
-- Merge restriction blocks merging by non-admins
-- Environment protection blocks exfiltration of release secrets
-- With a GitHub App, tokens auto-expire in ~1 hour
-- With a PAT, rotate periodically
-
-### How tokens interact with `permissions:` and `actions/checkout`
-
-Two independent authentication paths exist in every workflow:
-
-1. **Git CLI** (`git push`): authenticates with the token from
- `actions/checkout`. When no explicit token is passed, this defaults to
- `GITHUB_TOKEN` scoped by the `permissions:` block. When an explicit token
- is passed, that token's scopes apply instead.
-2. **GitHub API** (`gh pr create`, `gh api`): `claude-code-action` overwrites
- the `GITHUB_TOKEN` env var with its `github_token` input.
-
-All workflows should pass the bot token to both paths.
-
-## Prompt injection threat model
-
-| Workflow | Injection surface | Attacker control | Mitigations |
-|----------|-------------------|-------------------|-------------|
-| **review** | PR diff content, review body on bot PRs | Full (any PR) / Medium (reviewers) | Fixed prompt, merge restriction |
-| **triage** | Issue body | Partial (structured skill) | Fixed prompt, merge restriction, environment protection |
-| **mention** | Comment body on any issue/PR | Full | Fixed prompt, merge restriction, engagement verification |
-| **ci-fix** | Failed CI logs | Minimal (must break CI on default branch) | Fixed prompt, automatic trigger |
-| **renovate** | None | None | Fixed prompt, scheduled trigger |
-
-### Secret exfiltration via modified workflows
-
-The most dangerous attack from a leaked bot token is not merging malicious
-code — it's exfiltrating other secrets:
-
-1. Push a branch with a modified workflow that references a secret
-2. Create a PR — the modified workflow runs from the PR branch
-3. For same-repo PRs, all **repo-level** secrets are available
-4. Environment-protected secrets are NOT available (require deployment approval)
-
-This is why release secrets must be in a protected environment, not repo-level
-secrets.
-
-## Future hardening
-
-- Migrate from PAT to GitHub App for ephemeral tokens (~1 hour vs indefinite)
-- Workflow dispatch isolation: split workflows into analysis (GITHUB_TOKEN) +
- push (separate workflow with bot token) so the token never touches untrusted
- input
-- Disable "Allow GitHub Actions to create and approve pull requests" in repo
- settings
-
-## GitHub API: event types for PR comments
-
-GitHub treats PRs as a superset of issues. Comments on a PR arrive via
-different event types depending on where they're posted:
-
-- **Conversation tab** → `issue_comment` event. The PR is at
- `github.event.issue.pull_request`. The PR number is
- `github.event.issue.number`.
-- **Files changed (inline)** → `pull_request_review_comment` event. The PR is
- at `github.event.pull_request`. There is no `github.event.issue`.
-- **Review submission** → `pull_request_review` event (type: `submitted`). The
- review is at `github.event.review`. The PR is at
- `github.event.pull_request`.
-
-Individual inline comments from a review also fire as separate
-`pull_request_review_comment` events.
-
-## Rules for modifying workflows
-
-- **No role-based gating**: Don't check `author_association` (OWNER, MEMBER,
- etc.) to decide whether to run. The merge restriction is the security
- boundary. Use technical criteria: fork detection, loop prevention, trigger
- phrases.
-- **Adding `allowed_non_write_users`** to a workflow with user-controlled
- prompts requires security review.
-- **All Claude workflows** must include
- `--append-system-prompt "You are operating in a GitHub Actions CI environment. Use /tend-running-in-ci before starting work."`.
-- **Token choice**: All Claude workflows use the bot token for consistent
- identity.
-- **`permissions:` block**: Set `contents: read` for read-only workflows.
-- **Sensitive secrets** must be in protected environments, never repo-level.