Failed subagent runs left throwaway helpers (_encode_commit_payload.py,
_emit_payload.py) in the shared working tree, polluting git status and
tripping gitea_lock_issue / pre-flight purity gates.
Add an 'Agent temp artifact cleanup' runbook section requiring deletion
of _encode_*/_emit_*/_inline_* helpers when the MCP commit completes or
aborts, prefer scratchpad payload preparation, and document the cleanup
checklist. Back it with .gitignore patterns so strays cannot block
issue locks for later sessions, and pin both with doc-contract tests
(including a repo-root scan asserting the artifacts stay removed).
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Require mutations only from branches/ worktrees after proving project
root, cwd, branch, stable main-checkout branch, and session worktree
path. Surface in portable skill, runbooks, wiki, operator guide, and
start-issue template.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Require lease verification (open PRs, branches, worktrees, leases,
merged completion) before any issue or PR work. Surface the rule in
the portable skill, Gitea runbooks, operator guide, and start-issue
template; add doc-contract tests.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
Document that build triggers live on the gated jenkins-write-mcp server,
not the read-only jenkins-mcp surface. Add registration and safety-model
cross-links plus doc tests that fail if trigger tools reappear on the read
boundary.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
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]>
sysadminandClaude Opus 4.8
