docs: define task-scoped Gitea MCP execution profile model (#12) #21

2026-07-01T12:03:46-05:00

jcwalker3 commented

2026-07-01 12:03:46 -05:00

Closes #12
Roadmap parent: #10

Summary

Adds docs/gitea-execution-profiles.md defining the task-scoped execution profile model for gitea-mcp. Documentation/model only — no runtime behavior.

The doc covers:

Principle — "the LLM is not the role; the MCP profile is the role." Roles are task-scoped, not assigned to a model; conflicting roles are separated by identity, not by prompt.
Profile model — metadata shape: profile_name, authenticated_username, allowed_operations, forbidden_operations, token_source_name, audit_label, and capability booleans (can_approve_prs, can_merge_prs, can_push_branches, can_mutate_issues, can_author_impl_prs).
Five reference profiles — gitea-issue-manager, gitea-author, gitea-reviewer, gitea-merger, gitea-owner, each with allowed/forbidden ops and booleans.
Operation model — coarse categories; forbidden wins over allowed; deny-by-default.
Identity + fail-closed rules — active profile and verified identity (via gitea_whoami, #11) must be known before any mutation; ambiguity = denial.
Self-review / self-merge prevention — a session must not approve/merge a PR authored by the same authenticated user (compares verified gitea_whoami login vs PR author).
Token handling — token_source_name is a name only; values never logged/returned/committed.
Boundary separation — no Jenkins/Ops/GlitchTip/Release/deploy/production behavior.
Roadmap links — explicitly defers runtime config (#19), discovery (#13), eligibility (#14), review (#15), merge (#16), audit (#18).

Files changed

docs/gitea-execution-profiles.md (new, +215 lines) — only file changed.

Validation

git diff --check → clean (no whitespace errors).
python3 -m py_compile mcp_server.py tests/test_mcp_server.py → OK (code untouched, sanity check).
pytest tests/test_mcp_server.py → 30 passed.
git diff master --stat → 1 file, additions only.

Explicit statements

Runtime profile switching is NOT implemented — model/docs only.
No review/merge/eligibility workflow was implemented — those are #14/#15/#16.
No multi-token loading implemented — that is #19.
No secrets or tokens were added. token_source_name refers to a variable/key name only; no token values appear anywhere.

Scoped to #12 only. Does not touch #13–#19. Do not merge — awaiting independent review.

Closes #12 Roadmap parent: #10 ## Summary Adds `docs/gitea-execution-profiles.md` defining the **task-scoped execution profile model** for `gitea-mcp`. Documentation/model only — no runtime behavior. The doc covers: - **Principle** — "the LLM is not the role; the MCP profile is the role." Roles are task-scoped, not assigned to a model; conflicting roles are separated by *identity*, not by prompt. - **Profile model** — metadata shape: `profile_name`, `authenticated_username`, `allowed_operations`, `forbidden_operations`, `token_source_name`, `audit_label`, and capability booleans (`can_approve_prs`, `can_merge_prs`, `can_push_branches`, `can_mutate_issues`, `can_author_impl_prs`). - **Five reference profiles** — `gitea-issue-manager`, `gitea-author`, `gitea-reviewer`, `gitea-merger`, `gitea-owner`, each with allowed/forbidden ops and booleans. - **Operation model** — coarse categories; forbidden wins over allowed; deny-by-default. - **Identity + fail-closed rules** — active profile and verified identity (via `gitea_whoami`, #11) must be known before any mutation; ambiguity = denial. - **Self-review / self-merge prevention** — a session must not approve/merge a PR authored by the same authenticated user (compares verified `gitea_whoami` login vs PR author). - **Token handling** — `token_source_name` is a *name* only; values never logged/returned/committed. - **Boundary separation** — no Jenkins/Ops/GlitchTip/Release/deploy/production behavior. - **Roadmap links** — explicitly defers runtime config (#19), discovery (#13), eligibility (#14), review (#15), merge (#16), audit (#18). ## Files changed - `docs/gitea-execution-profiles.md` (new, +215 lines) — only file changed. ## Validation - `git diff --check` → clean (no whitespace errors). - `python3 -m py_compile mcp_server.py tests/test_mcp_server.py` → OK (code untouched, sanity check). - `pytest tests/test_mcp_server.py` → **30 passed**. - `git diff master --stat` → 1 file, additions only. ## Explicit statements - **Runtime profile switching is NOT implemented** — model/docs only. - **No review/merge/eligibility workflow was implemented** — those are #14/#15/#16. - **No multi-token loading implemented** — that is #19. - **No secrets or tokens were added.** `token_source_name` refers to a variable/key name only; no token values appear anywhere. Scoped to #12 only. Does not touch #13–#19. **Do not merge** — awaiting independent review.

jcwalker3 added 1 commit 2026-07-01 12:03:47 -05:00

docs: define task-scoped Gitea MCP execution profile model (#12 ) 5aad2e62d9

Add docs/gitea-execution-profiles.md defining the execution profile
model for gitea-mcp: profile metadata shape, five reference profiles
(gitea-issue-manager, gitea-author, gitea-reviewer, gitea-merger,
gitea-owner), allowed/forbidden operation model, identity + fail-closed
rules, and self-review/self-merge prevention.

Model/documentation only. No runtime profile switching, no multi-token
loading, no approve/merge/eligibility workflow, no secrets. Runtime
config (#19), discovery (#13), eligibility (#14), review (#15), merge
(#16), and audit logging (#18) are explicitly deferred.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

jcwalker3 commented

2026-07-01 12:05:58 -05:00

Independent review for issue #12 is held due reviewer eligibility.

Validation performed:

PR #21 is open and targets master.
Authenticated Gitea account is jcwalker3, which matches the PR author, so I cannot approve this PR from this account.
Head reviewed: 5aad2e6.
Changed files verified exactly: docs/gitea-execution-profiles.md.
git fetch --all --prune completed.
git diff --check prgs/master...5aad2e6 passed.
git diff --name-only prgs/master...5aad2e6 returned only docs/gitea-execution-profiles.md.
python3 -m py_compile mcp_server.py tests/test_mcp_server.py passed.
pytest tests/test_mcp_server.py passed: 30 passed.

Manual review notes:

Scope is docs-only: no source code, tests, scripts, runtime profile switching, multi-token loading, approve/merge/eligibility implementation, secrets, or real credential config changed.
The doc covers LLMs not being permanent roles, task-scoped profiles, required active profile and authenticated identity before mutation, fail-closed unknown profile/identity, self-review/self-merge prevention, token redaction rules, Gitea boundary separation, and roadmap ownership for #13/#14/#15/#16/#18/#19.
Example profiles are defined for gitea-issue-manager, gitea-author, gitea-reviewer, gitea-merger, and gitea-owner.
The profile model documents profile name, authenticated username, allowed/forbidden operations, token source name, audit label, and capability booleans for approve, merge, branch push, issue mutation, and implementation PR authorship.
No Jenkins, Ops, GlitchTip, Release, deploy, rollback, migration, restart, or production behavior found.

Blocker: reviewer is ineligible from the current authenticated Gitea account (jcwalker3). A different reviewer account is required to approve.

Independent review for issue #12 is held due reviewer eligibility. Validation performed: - PR #21 is open and targets `master`. - Authenticated Gitea account is `jcwalker3`, which matches the PR author, so I cannot approve this PR from this account. - Head reviewed: `5aad2e6`. - Changed files verified exactly: `docs/gitea-execution-profiles.md`. - `git fetch --all --prune` completed. - `git diff --check prgs/master...5aad2e6` passed. - `git diff --name-only prgs/master...5aad2e6` returned only `docs/gitea-execution-profiles.md`. - `python3 -m py_compile mcp_server.py tests/test_mcp_server.py` passed. - `pytest tests/test_mcp_server.py` passed: 30 passed. Manual review notes: - Scope is docs-only: no source code, tests, scripts, runtime profile switching, multi-token loading, approve/merge/eligibility implementation, secrets, or real credential config changed. - The doc covers LLMs not being permanent roles, task-scoped profiles, required active profile and authenticated identity before mutation, fail-closed unknown profile/identity, self-review/self-merge prevention, token redaction rules, Gitea boundary separation, and roadmap ownership for #13/#14/#15/#16/#18/#19. - Example profiles are defined for `gitea-issue-manager`, `gitea-author`, `gitea-reviewer`, `gitea-merger`, and `gitea-owner`. - The profile model documents profile name, authenticated username, allowed/forbidden operations, token source name, audit label, and capability booleans for approve, merge, branch push, issue mutation, and implementation PR authorship. - No Jenkins, Ops, GlitchTip, Release, deploy, rollback, migration, restart, or production behavior found. Blocker: reviewer is ineligible from the current authenticated Gitea account (`jcwalker3`). A different reviewer account is required to approve.

jcwalker3 reviewed 2026-07-01 12:15:05 -05:00

jcwalker3 left a comment

Approved for merge based on documentation validation.

jcwalker3 merged commit 28feef3c11 into master

2026-07-01 12:15:06 -05:00

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: Scaled-Tech-Consulting/Gitea-Tools#21