Bootstrap repo-tracked wiki pages (10 required pages), the operator-
confirmed sync script, PR template publication gate, and safety tests so
Gitea-Tools can publish to the live Gitea Wiki per issue #224.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
PR closure had no first-class capability: agents could close PRs through
gitea_edit_pr(state=closed) with no close-specific capability proof, and
gitea_resolve_task_capability(close_pr) failed as unknown, leaving the
broad edit path as an untracked close fallback.
Add close_pr to the resolver TASK_MAP (gitea.pr.close, author-side) and
gate gitea_edit_pr(state=closed) on the same operation: without it the
close fails closed before any auth or API call, with reasons and a
structured permission_report; with it the close proceeds and is audited
as a distinct close_pr action carrying the required capability. Reject
invalid state values outright so case variants cannot bypass the gate.
Generalize the profile gate helper (_profile_operation_gate) and document
the PR comment / PR edit / PR close capability split.
Co-Authored-By: Claude Fable 5 <[email protected]>
- Add gitea_get_pr_review_feedback: read-only MCP-native discovery of
formal PR review verdicts (APPROVED / REQUEST_CHANGES / COMMENT) with
latest-state-per-reviewer, blocking change-request and approval
summaries, reviewed-head vs current-head staleness, dismissed/PENDING
handling, credential redaction of review bodies, no endpoint URLs
without the reveal opt-in, and a fail-closed gitea.read gate that
returns feedback_not_attempted with a structured #142 permission
report and zero API calls.
- Add task/role guards to gitea_resolve_task_capability: new
stop_required and task_role_guidance outputs, and a distinct
address_pr_change_requests author task, so a review/merge request
under an author profile returns explicit STOP guidance instead of
silently degrading into author-side mutations, and author-side
remediation is explicitly barred from review verdicts and merges.
- Add build_validation_report: validation reporting helper that
distinguishes passed / failed / skipped / not-run, requires the exact
output for failures, rejects vague statuses, and never implies
full-suite success unless the full-suite command passed.
- Document task/role alignment (review vs author-fix vs merge vs
comment workflows with required identity, allowed/forbidden actions,
and stop conditions), MCP-native review feedback discovery, and
validation reporting discipline in docs/llm-workflow-runbooks.md.
- Add tests/test_review_feedback.py (22 tests) covering discovery,
staleness, redaction, URL hiding, fail-closed gating, role guards for
author/reviewer profiles, and validation report semantics.
Closes#167
Co-Authored-By: Claude Fable 5 <[email protected]>
- Updated jenkins-readonly and glitchtip-readonly skills in _PROJECT_SKILLS:
- Descriptions and notes now use actual server names (jenkins-mcp, glitchtip-mcp)
- Explain historical -readonly skill names vs registration in mcp-control-plane #55
- Note gated trigger in jenkins-mcp (see #56), partial filing in glitchtip (see #57)
- Updated docs/safety-model.md: naming note, corrected mutation gating claims for trigger/filing
- Updated docs/architecture/jenkins-readonly-build-status-design.md: naming note, updated Phase 1 to account for gated trigger
- No behavior change to skill status/availability; no secrets exposed
- AC: stale naming explained, actual names documented, Jenkins claims corrected, GlitchTip filing as partial, no over-claiming
Closes#154
Record the #139 accepted decision as a deployment doc: two static
per-role MCP namespaces (gitea-author, gitea-reviewer), one credential
per process, with dynamic profile switching and dispatcher routing
explicitly rejected for now. Covers rationale (audit clarity, credential
concentration, two-party review boundary, fail-closed behavior),
reference-only client setup via GITEA_MCP_CONFIG/GITEA_MCP_PROFILE,
the 'Auth unsupported' client-badge caveat, and reconnect/reload
requirements after profile/config/code changes. Cross-linked from the
execution-profiles model doc and the workflow runbooks; guarded by
docs-content tests.
Closes#143
Co-Authored-By: Claude Fable 5 <[email protected]>
- Add aliases 'issue.comment' and 'issue_comment' to GITEA_OPERATION_ALIASES so short names normalize to gitea.issue.comment
- Grant 'issue.comment' (and short) in v2 example profiles for example-author and example-reviewer
- Grant in gitea-mcp.example.json mdcps-reviewer
- Update docs example profiles
- Add test coverage for new aliases and normalization
This enables gitea_create_issue_comment and list for profiles that include it, while preserving fail-closed for others and separation of duties (issue.comment does not imply pr.review etc).
Closes#137
Add three read-only capability-discovery tools so new LLM sessions can
learn the workflow rules and available project skills from the MCP
server instead of long pasted operator prompts:
- mcp_get_control_plane_guide: active profile, authenticated identity
(fail-soft; unresolved identity returns STOP instructions),
allowed/forbidden operations, profile-aware guidance (author profiles
are told review/approve/merge is forbidden; reviewer profiles are told
review/merge requires eligibility checks and a pinned head SHA; mixed
profiles get a misconfiguration warning), and the standing rules: hard
stops, fail-closed behavior, head-SHA pinning, merge confirmation,
redaction, author/reviewer/merger separation, profile switching, and
identity verification.
- mcp_list_project_skills: registry of ten project workflows (issue
authoring, PR creation, PR review, PR merge, issue comments, profile
switching, redaction/security review, Jenkins read-only, GlitchTip
read-only, release/operator) with description, when-to-use, required
operations, status, and per-profile availability. Unimplemented
services are listed as designed-not-implemented rather than omitted.
- mcp_get_skill_guide: step-by-step guide per skill; unknown names fail
closed with the list of valid names.
All three are read-only and change no existing gate or permission.
Normal output contains no endpoint URLs or keychain IDs; the guide
includes the server host only under GITEA_MCP_REVEAL_ENDPOINTS=1.
Tests (tests/test_operator_guide.py, 17 new): profile-aware guidance
for author/reviewer, unresolved-identity STOP, read-only behavior,
redaction defaults and reveal opt-in, rules coverage, registry
completeness and profile awareness, unimplemented-service marking,
fail-closed unknown skill names.
Docs: llm-workflow-runbooks.md now tells new sessions to call the guide
tools first.
Closes#128
Co-Authored-By: Claude Fable 5 <[email protected]>
Add gitea_list_issue_comments and gitea_create_issue_comment so
discussion/design workflows can read and post issue comments through
the MCP layer instead of direct API scripts.
- List requires gitea.read; create requires gitea.issue.comment —
gated separately from the gitea.pr.* review/merge family, fail closed.
- Issue comments never touch PR review endpoints.
- LLM-safe output: comment id/author/timestamps/body only; web links
appear solely under the GITEA_MCP_REVEAL_ENDPOINTS admin opt-in.
- Create operations are audit-logged (create_issue_comment) and errors
are redacted before being raised.
- Tests cover list/create success, permission blocks (including PR
review permissions not granting issue comments), forbidden-overrides,
empty body, missing issue with redacted error, endpoint separation,
and reveal opt-in.
- Document issue comments versus PR reviews in
docs/gitea-execution-profiles.md.
Closes#126
Co-Authored-By: Claude Fable 5 <[email protected]>
Promote the #103 minimal alias map to the documented public table
GITEA_OPERATION_ALIASES and add the #106 enforcement layer:
- normalize_operation(op, service): canonical namespaced names; legacy
spellings accepted only via the explicit table; unknown, ambiguous,
and cross-service names fail closed.
- check_operation(op, allowed, forbidden, service): normalizes BOTH the
requested operation and the profile lists before any membership
check; forbidden always overrides allowed; unnormalizable allowed
entries grant nothing and unnormalizable forbidden entries deny the
request, so normalization can never silently widen permissions;
empty/missing allowed list denies everything.
- gitea_check_pr_eligibility now routes its capability check through
check_operation, fixing the mismatch where canonical namespaced
profile ops (gitea.pr.merge) never matched the raw action (merge)
and namespaced forbidden entries were never enforced.
- Document the normalization table and enforcement rules in
docs/gitea-execution-profiles.md, replacing the stale 'enforcement
out of scope' caveat.
- tests/test_op_normalization.py: full #106 matrix (27 tests) —
qualified/legacy allowed and forbidden, unknown, ambiguous, service
mismatch, forbidden-overrides-allowed, empty/missing allowed,
duplicates after normalization, no permission widening, and
eligibility integration proving normalization happens before
enforcement. Existing v1/env unqualified behaviour stays compatible.
Closes#106
Co-Authored-By: Claude Fable 5 <[email protected]>
Make the nine-line compact Controller Handoff the default end-of-task
format; reserve the long Controller Handoff Summary for high-risk/complex
tasks (merge/tag/release, failed validation, blocked gates, secrets/prod,
complicated owner decisions, cross-repo state, or explicit owner request).
Compact form is for controller-LLM readability, safety confirmations are
never omitted, and PR bodies still carry full review detail.
Updates SKILL.md §K, llm-workflow-runbooks.md, and the start-issue /
review-pr templates. Documentation only.
Refs #101. Closes#108.
Co-Authored-By: Claude Fable 5 <[email protected]>
Add docs/architecture/jenkins-job-mapping-design.md: declarative versioned
mapping config (exact-match repo/branch entries, no globs, fail-closed load
on malformed/duplicate entries), resolution semantics for multibranch/
single/parameterized-view job types with URL-encoded branch and PR-<n>
addressing, branch-pinned-over-repo-wide precedence, fork PRs resolving via
base repo only, explicit machine-checkable no-match payload (never guess or
probe job names), config location in the jenkins-mcp package (no secrets,
env-overridable path), a read-only jenkins_resolve_job tool surface, and a
mocked-config/mocked-Jenkins testing strategy.
Design only; no implementation, no code behavior changed, no Jenkins write
actions introduced.
Co-Authored-By: Claude Fable 5 <[email protected]>
Add docs/developer-testing-guidelines.md covering test commands, targeted
runs, syntax/diff checks, adding MCP tool tests, safe API/auth mocking,
profile/allowed-operation gate tests, self-review/self-merge gate tests,
no-secret regression expectations, unit vs future Docker integration tests,
and read-only vs mutating tool expectations. Link it from the README Tests
section and note the suite table is non-exhaustive.
Documentation only; no code behavior changed.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Automate the documented release-tag checklist (#48) without bypassing safety
gates.
scripts/release-tag:
- Requires a SemVer tag (vMAJOR.MINOR.PATCH); validates before any git/network.
- Fetch/prune first, then refuses: dirty worktree, non-master branch, local
master != remote master, HEAD not on remote master, and an existing local or
remote tag of the same name.
- Runs the full suite by default; --skip-tests is an explicit opt-out that warns.
- Creates an ANNOTATED tag (git tag -a), never lightweight.
- Safe by default: no push unless --push; --dry-run prints planned actions and
changes nothing. Supports --notes-file <path> for the annotation message.
- Prints: commit, tag, tests_run, tag_created, tag_pushed.
- Env injection points for testing/CI: RELEASE_TAG_REMOTE, RELEASE_TAG_TEST_CMD.
tests/test_release_tag.py (14 cases): valid SemVer dry-run; invalid version;
dirty worktree; non-master; master/remote mismatch; existing tag; missing
notes-file; annotated-not-lightweight; no-push-without-flag; push-only-with-flag;
notes-file message; --skip-tests warns; default runs tests (fail blocks tag,
pass tags). Each test builds a throwaway repo with a LOCAL bare remote (cloned,
not pushed) and stubs the test command — no network, no real tags, no pushing
from the project repo.
Docs: reference scripts/release-tag from the runbook, SKILL, and the release-tag
template (script preferred; manual steps are the fallback).
Full suite 305 passed / 0 failures; bash -n clean; git diff --check clean; no
secrets.
Closes#50. Refs #48.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Documents and enforces rules for closed-not-merged PR reconciliation, direct-master-push prevention, and issue label cleanup.
Rules added:
- Explicit definitions for Merged, Landed, Closed-not-merged, and Reconciled.
- A PR is done only when Gitea reports it merged or reconciliation proves content is present on master.
- Direct push to master is forbidden except as a documented recovery exception.
- PRs closed but not merged trigger the reconciliation process.
- Branch and worktree cleanup is forbidden until merge or reconciliation is confirmed.
- Final reports require PR metadata and Git content verification.
Closes#51.
Formalize the branch↔issue relationship and add a release/version-tagging policy.
Branch/issue linkage:
- scripts/worktree-start now validates branch names: implementation branches
must match (fix|feat|docs|chore)/issue-<number>-<slug>; review branches
review/pr-<number>-<slug>. Untraceable names are rejected with a clear error
(exit 2). New --allow-unlinked override for genuine exceptions. --dry-run
preserved.
- Documented issue → branch → worktree → PR → cleanup traceability in the
runbook and the portable SKILL, including the claim-comment convention and
Closes #n / Refs #n PR-body usage.
- Noted that Gitea exposes no native issue→branch API field (only a PR head
branch), so linkage is enforced via branch name + claim comment + PR body +
cleanup.
Versioning / tagging policy (docs only; no release automation yet):
- SemVer vMAJOR.MINOR.PATCH (v0.x.y while unstable) with PATCH/MINOR/MAJOR bump
rules.
- Annotated tags only, from the exact commit on remote master, only after the
full suite passes, with release notes referencing merged PRs/issues. Never tag
feature branches, dirty worktrees, unreviewed/self-authored work, or commits
not on remote master.
- Release runbook in the runbook + SKILL, plus a new
skills/llm-project-workflow/templates/release-tag.md prompt template.
Tests: worktree-start branch validation — accepts fix/feat/docs/chore/issue-*
and review/pr-*, rejects fix/random-name / my-branch / non-numeric issue,
honors --allow-unlinked, preserves --dry-run. Full suite 291 passed / 0 failures;
bash -n clean; git diff --check clean; no secrets.
Release-tag automation (a scripts/release-tag helper) intentionally deferred to a
later issue to keep this diff narrow and testable.
Closes#48. Refs #38, #39, #46.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Extract the project's operating rules into a reusable, project-agnostic skill
so any repo can adopt the same safe LLM workflow.
- skills/llm-project-workflow/SKILL.md: issue-first; isolated branch worktrees
(main checkout = orchestration only); distinct author/reviewer identities and
profile safety (secrets by reference only; stop if authenticated user == PR
author); branch naming; start/review/merge/cleanup workflows; fail-closed
cases; recovery patterns; and an "Adapting to a project" table for the
forge-specific names.
- templates/: copy/paste prompts for start-issue, review-pr, merge-pr,
recover-bad-state, worktree-cleanup.
- Link the skill from README.md and docs/llm-workflow-runbooks.md (the runbook
is framed as the Gitea-specific application of the portable skill).
Docs-only; no code, no secrets, safe placeholder examples only. No change to
MCP runtime, Gitea API, credential storage, or worktree helpers.
Checks: full suite 287 passed / 0 failures; git diff --check clean; secret scan
of skills/ clean.
Closes#46. Refs #38, #39.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Finishes the isolated-worktree standard begun in #38 (which merged the
branches/ gitignore, runbook, and scripts/worktree-start). Adds the two
remaining helpers and their tests.
- scripts/worktree-review: isolated DETACHED review worktree under
branches/review-<branch> (fetch/prune first, refuse to overwrite, print path,
--dry-run). Detached so a reviewer cannot accidentally commit and review work
never blocks the author's implementation folder.
- scripts/worktree-clean: the only deleting helper — removes a branches/
worktree after merge/close, refuses a dirty worktree (no --force), optionally
safe-deletes a merged branch (git branch -d), fetch/prune first, --dry-run.
Deletes nothing unless explicitly invoked.
- tests/test_worktrees.py: path generation + refuse-to-overwrite for all three
helpers via --dry-run (no real worktrees/branches/network/deletions).
- runbook: reference worktree-review / worktree-clean and the --dry-run flag.
Checks: bash -n clean on all three scripts; git diff --check clean; full suite
286 passed, 0 failures.
Closes#39. Follow-up to #38.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Make the interactive profile menu feel like a real terminal menu, via a new
injectable MenuIO abstraction (no menu logic change, no auth/secret-storage
change).
- Single-key top-level actions in a TTY (termios/tty raw read); no Enter
needed. Non-TTY / test runs fall back to line input.
- Enter backs out: Enter (or 0) on the main menu quits; Enter cancels any
submenu/profile prompt and returns.
- Profile chooser: everywhere a profile is needed, show a numbered list and
pick by key (1-9), with an explicit 'm) type a name manually' path and Enter
to cancel. Empty config handled gracefully.
- Clear screen before redrawing the main menu and chooser — TTY only; never
emits clear codes in non-TTY/test runs.
- Result actions (validate/test-auth/whoami/eligibility) print a concise result
then pause for a keypress in a TTY; non-TTY never blocks.
Helpers: read_key (via default_io) / choose_menu_option / choose_profile /
clear_screen / pause_for_key, plus MenuIO(is_tty, clear_enabled). TTY detected
with sys.stdin.isatty() and sys.stdout.isatty(); stdlib only.
Safety unchanged: no tokens/passwords printed, no raw config dumps, no
.env.personal, no change to auth behavior or secret storage.
Tests: rewrote menu tests around a scripted _FakeIO (no real terminal): single-
key select + clear, main-menu Enter/0 quit, submenu Enter cancel (no change),
chooser lists/selects/no-profiles/manual/out-of-range, non-TTY line fallback,
clear-only-when-enabled, pause never hangs non-TTY, and add-flow proving the
token value never reaches disk or stdout.
Docs: runbook note on single-key nav / Enter back-out / numbered chooser.
scripts/gitea-config-menu unchanged.
Closes#36. Refs #31, #34.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
sysadmin
