From ee812699a49813f076770b761cc5e8c5330a3ab0 Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Sun, 30 Aug 2026 12:08:38 +0000 Subject: [PATCH] refactor(gitea-branches): retrofit to the ADR-0020 context contract Description 688 -> 282 chars, body 435 -> 293 words, Gotchas 5 entries/54% of body -> 3/23.5%. Clears the description FAIL and the Gotchas suggestion. Cut the second trigger register (six re-quoted user phrasings) and the capability enumeration; both moved to a new Boundaries section in the skill's own README. Kept all three boundary clauses -- git-branches, git-history and gitea-prs each defend a real activation steal, and gitea-prs is now the only guard on the branch/PR collision in either direction since gitea-prs's own retrofit narrowed its boundary to issues. Written as one arrow per target: the resolver extracts only the first name per arrow clause, so conjoined targets go unchecked. Two Gotchas deleted -- one paraphrased the step below it (its non-obvious half, the get_me/list_my_repos token-scope block, was folded into that step), the other is carried in full by references/branches.md:40-52. Repoint two reference pointers the rename broke: branches.md and commits.md named Gotchas by titles this retrofit changed. Now named by stable descriptors. Refs #99 --- .../.apm/skills/gitea-branches/README.md | 12 ++++++++ .../gitea/.apm/skills/gitea-branches/SKILL.md | 30 +++++++------------ .../gitea-branches/references/branches.md | 2 +- .../gitea-branches/references/commits.md | 2 +- 4 files changed, 25 insertions(+), 21 deletions(-) diff --git a/plugins/gitea/.apm/skills/gitea-branches/README.md b/plugins/gitea/.apm/skills/gitea-branches/README.md index 1be8bcc..3a99f72 100644 --- a/plugins/gitea/.apm/skills/gitea-branches/README.md +++ b/plugins/gitea/.apm/skills/gitea-branches/README.md @@ -10,6 +10,18 @@ history (list commits, get a single commit's full detail) against a Gitea reposi pagination conventions specific to Gitea's API (e.g. refusing to delete a protected branch without explicit confirmation, and treating unexpected 404s as possible masked 403s). +## Boundaries + +This skill operates on the Gitea server via the MCP tools, never on your local checkout. Branch +and commit-history work against the working copy belongs to `git-branches` and `git-history`. +Branch references that only exist relative to a pull request — a PR's head or base branch, and +cross-repo fork PR heads in particular — belong to `gitea-prs`; `list_branches` cannot see a fork's +head at all. + +The skill triggers on phrasings like "list branches", "create a branch", "delete a branch", +"what commits are on this branch", "show commit ", and "what changed in that commit", even +when the user does not say "Gitea", as long as the repo's remote is a Gitea instance. + ## Before you start Requires a Gitea MCP server configured with a token that has `write:repository` scope. This is diff --git a/plugins/gitea/.apm/skills/gitea-branches/SKILL.md b/plugins/gitea/.apm/skills/gitea-branches/SKILL.md index 654ebfc..fc112ff 100644 --- a/plugins/gitea/.apm/skills/gitea-branches/SKILL.md +++ b/plugins/gitea/.apm/skills/gitea-branches/SKILL.md @@ -2,22 +2,16 @@ name: gitea-branches description: > - Use when managing Gitea repository branches — listing, creating, or deleting - branches — or inspecting commit history within a Gitea repo: listing commits - (optionally filtered by branch or file path) or getting full detail for a - single commit by SHA. Triggers on "list branches", "create a branch", - "delete a branch", "what commits are on this branch", "show commit ", - "what changed in that commit" — even if the user doesn't say "Gitea" - explicitly, as long as the repo's remote is a Gitea instance. Do not use for - local git branch/commit operations on your working copy (use git-branches or - git-history) or for PR-side branch references like cross-repo fork PR heads - (use gitea-prs). + Use when listing, creating, or deleting branches in a Gitea repository, or + reading its commit history — even when the user does not say "Gitea". Not a + local working copy's branches -> `git-branches`. Not local history -> + `git-history`. Not a PR's head or base branch -> `gitea-prs`. compatibility: Requires Gitea MCP server configured with a token with write:repository scope; this is confirmed to gate list_branches, create_branch, and delete_branch (Gitea gates reads behind write scope for repo-scoped operations), and is inferred by analogy (not explicitly confirmed by source docs) to also gate list_commits and get_commit. Requires git remote "origin" pointing to the Gitea instance. metadata: category: integration - version: "0.1.1" + version: "0.1.2" source_keys: - gitea-mcp-repo - gitea-mcp-slim-go @@ -28,11 +22,9 @@ allowed-tools: Bash mcp__gitea__list_branches mcp__gitea__create_branch mcp__git ## Gotchas -- **Never delete a protected branch (`main`/`master` by name, or `protected: true` from `list_branches`) without explicit confirmation.** `delete_branch` is a direct API call, not a local `git push` — there is no client-side force-push guard protecting it. Name-matching `main`/`master` is a convenient default but not authoritative — a repo can protect a differently-named default branch. When in doubt, call `list_branches` first and check `protected` on the target; treat deletion of any protected branch as a hard refusal unless the user explicitly confirms in the conversation. -- **404 may actually mean 403.** Gitea hides permission errors as not-found to avoid leaking resource existence. If any of these five tools returns 404 unexpectedly, check token scope (see `references/branches.md` / `references/commits.md`) before concluding the branch or commit doesn't exist. -- **Pagination is manual.** `list_branches` and `list_commits` return one page at a time — no auto-pagination in the MCP layer. When you need a complete list, iterate `page: 1, 2, ...` until the returned count is less than `per_page`. -- **Owner/repo always come from the git remote, never from `get_me`.** Resolve them via `git remote get-url origin` (Step 1 below). `get_me`/`list_my_repos` are blocked under the token scopes this skill assumes. -- **`create_branch`'s source is `old_branch`, not "wherever gitea-mcp feels like."** Omitting `old_branch` forks from the repo's server-side default branch — not necessarily the branch you're currently working on locally. If you want to branch from your current checkout, pass `old_branch` explicitly. +- **404 often means 403.** Gitea masks permission errors as not-found; on an unexpected one, check token scope before reporting a branch or commit missing. +- **Nothing auto-paginates.** `list_branches` and `list_commits` return one page; iterate `page` until the returned count is below `per_page`. +- **`delete_branch` has no force-push guard.** Check `protected` from `list_branches` first and require explicit confirmation — a protected branch need not be named `main`. ## Step 1 — Resolve owner and repo @@ -42,7 +34,7 @@ Before any tool call, extract `owner` and `repo` from the git remote: git remote get-url origin ``` -If origin is not set or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL." +`get_me` and `list_my_repos` are blocked under the token scope this skill assumes, so the remote is the only source. If origin is not set or the URL is not a Gitea URL, stop and report: "No Gitea remote found — set origin to your Gitea instance URL." ## Step 2 — Dispatch @@ -54,7 +46,7 @@ If origin is not set or the URL is not a Gitea URL, stop and report: "No Gitea r | `/gitea-branches commits [on ] [touching ]` | List commit history | | `/gitea-branches commit ` | Get full detail for one commit | -For branch operations (list/create/delete), read `references/branches.md`. +For branch operations (list/create/delete), read `references/branches.md` — it carries the call signatures, the `old_branch` source rule, and the protected-branch refusal in full. For commit operations (list/get), read `references/commits.md`. ## Step 3 — Report @@ -63,4 +55,4 @@ For reads: display branches as name + protected flag; display commits as SHA (sh For writes (create/delete): confirm the action taken, the branch name, and (for create) the base it forked from. -For errors: surface the HTTP code and message. If a 404 is unexpected, re-check token scope per the Gotchas above before reporting "not found" to the user. +For errors: surface the HTTP code and message, applying the 404 gotcha above before reporting "not found" to the user. diff --git a/plugins/gitea/.apm/skills/gitea-branches/references/branches.md b/plugins/gitea/.apm/skills/gitea-branches/references/branches.md index b94754d..ff4e239 100644 --- a/plugins/gitea/.apm/skills/gitea-branches/references/branches.md +++ b/plugins/gitea/.apm/skills/gitea-branches/references/branches.md @@ -65,7 +65,7 @@ A branch name collision returns `409 Conflict`. delete_branch owner: repo: branch: ``` -Before calling this, see the hard-refusal Gotcha in SKILL.md. If the target branch's name isn't +Before calling this, see the `delete_branch` Gotcha in SKILL.md. If the target branch's name isn't obviously a scratch/feature branch, call `list_branches` first and check `protected` on the matching entry — name-matching `main`/`master` alone isn't authoritative, since a repo can protect a differently-named default branch. Confirm explicitly with the user before deleting anything diff --git a/plugins/gitea/.apm/skills/gitea-branches/references/commits.md b/plugins/gitea/.apm/skills/gitea-branches/references/commits.md index fddeff5..19f8b3c 100644 --- a/plugins/gitea/.apm/skills/gitea-branches/references/commits.md +++ b/plugins/gitea/.apm/skills/gitea-branches/references/commits.md @@ -42,7 +42,7 @@ Dispatch defaults: **Response:** one object per commit: `sha`, `html_url`, `created`, `message` (when available), `author` (`{name, email, date}`, when available). -Paginate per the manual-pagination Gotcha in SKILL.md if you need more than one page of history. +Paginate per the pagination Gotcha in SKILL.md if you need more than one page of history. ## `get_commit`