Gitea-Tools/skills/llm-project-workflow/workflows/work-issue.md

task_mode, canonical, final_report_schema

task_mode	canonical	final_report_schema
work-issue	true	../schemas/work-issue-final-report.md

Work issue workflow (canonical)

Task mode: work-issue

This file is the canonical author/coder workflow for Gitea-Tools. Load it before any issue implementation mutation. Final report schema: schemas/work-issue-final-report.md.

Default task prompt:

Find the next eligible issue in this project, work on it only if all gates pass, and create a PR when complete.

Do not improvise around the gates. Follow project skills, MCP gates, and workflow rules exactly.

This is an author/coder workflow. It is not a reviewer workflow.

---

0. Load the canonical workflow first

Before starting issue work, check whether the project provides a canonical work-on-issue workflow through a project skill, runbook, or MCP helper.

If available, load it first and report:

• workflow source
• workflow version, commit, or hash
• whether this prompt conflicts with the loaded workflow

If the canonical workflow cannot be loaded and the project requires it, stop and produce a recovery handoff only.

1. Mode isolation

This run is work-issue mode only.

Do not:

• review PRs
• approve PRs
• request changes
• merge PRs
• close PRs unless the PR creation workflow explicitly does so through Gitea automation
• close unrelated issues
• mutate reviewer state
• perform reviewer-only actions
• create process-hardening issues unless explicitly authorized and the workflow switches to issue-creation mode

If the task requires review, merge, issue creation, or MCP repair mode, stop and produce a handoff for the correct workflow.

Do not mix modes in one run.

2. Start with live identity, profile, runtime, and capability checks

Prove:

• authenticated identity
• active author/coder profile
• repo/project
• runtime context
• exact capability for reading issues
• exact capability for claiming/locking issues, if available
• exact capability for branch creation, if handled through MCP
• exact capability for pushing branches, if applicable
• exact capability for creating PRs
• exact capability for commenting on issues or PRs, if needed

A nearby capability does not count.

Examples:

• create_issue does not authorize issue_comment
• review_pr does not authorize merge_pr
• create_pr does not authorize merge_pr
• issue_comment does not authorize create_issue
• gitea.read does not authorize issue claim, PR creation, or branch mutation

If capability cannot be proven, stop and produce a recovery handoff only.

2A. Pre-task role routing (#139)

Before issue selection or any mutation, resolve the composite author task:

• gitea_route_task_session(task_type="work-issue", remote=…) — must return route_result: allowed_current_session and downstream_allowed: true
• gitea_resolve_task_capability(task="work_issue", remote=…) — must show required_role_kind: author and allowed_in_current_session: true

Hyphen (work-issue) and underscore (work_issue) aliases are equivalent. If routing returns ambiguous_task_stop, wrong_role_stop, or route_to_author_session, stop and produce a recovery handoff only — do not fall back to reviewer tools or guess a different profile.

3. Stop immediately on blocked infrastructure

If any of the following appears, stop immediately:

• infra_stop
• MCP reconnect failure
• stale capability state
• dirty control checkout
• dirty task worktree
• missing capability
• workspace mismatch
• stale target branch state
• broken canonical workflow loading
• failed required preflight
• capability resolver warning that says the current state may be unsafe
• stale or inconsistent runtime context

Do not continue issue selection, claiming, implementation, validation, commit, push, PR creation, cleanup, or handoff mutation.

Produce an executable recovery handoff only.

Blocked recovery handoffs must not include direct commit, push, or PR replay commands.

Blocked handoffs must say to rerun the full workflow after the blocker clears.

4. Main checkout rule

The main project checkout must stay on master, main, or dev.

Do not do task work in the main checkout.

Do not edit files in the main checkout.

Do not run tests in the main checkout.

Do not commit from the main checkout.

Do not create PRs from the main checkout.

All task work must happen under the project’s branches/ directory.

No exceptions for small fixes, docs, tests, cleanup, conflict resolution, emergencies, or “just one file.”

If the main checkout is dirty before selection, stop and produce a recovery handoff.

If the main checkout becomes dirty during the run, stop and produce a recovery handoff unless the change is explicitly allowed by the canonical workflow.

Stacked PRs (explicit exception, #484)

Normal author work stays base-equivalent to master/main/dev. A stacked PR — deliberately based on another unmerged PR's branch — is the only sanctioned non-master base, and only when the operator/controller explicitly chooses it:

• Branch the branches/ worktree from the dependency's branch, then lock with gitea_lock_issue(..., stacked_base_branch=<dep-branch>, stacked_base_pr=<open-PR#>). The lock fails closed unless that open PR owns the branch; arbitrary or stale branches are rejected.
• Open the PR with gitea_create_pr(base=<dep-branch>). The body must state: Stacked on PR #<X> / issue #<Y>, Base branch: <dep-branch>, Head branch: <this-branch>, Do not merge before PR #<X>, and note retarget/rebase to master after the dependency lands if required.
• This does not relax the main-checkout rule or bypass the issue lock — work still happens under branches/, and the approved base is recorded on the lock.

5. No raw MCP repair during normal issue work

Do not run pkill, kill MCP processes, edit MCP config, restart servers, or perform control-checkout repair during normal issue work.

If MCP repair is required, stop issue work and produce a separate CONTROL-CHECKOUT REPAIR MODE handoff.

Do not mix MCP repair mode with work-on-issue mode.

Do not use successful repair as permission to resume the same issue workflow. After repair, rerun the full workflow from the beginning.

6. No background task tools

Do not use schedule, manage_task, background jobs, async waits, delayed task tools, or monitoring tasks during issue work.

Use direct commands and MCP tools only.

If a required action cannot complete synchronously, stop and produce a recovery handoff.

Long synchronous commands, such as a test suite, are allowed only if they are run directly and reported with exact command, working directory, and result.

Do not say “I will check later,” “I will monitor,” or “I will continue in the background.”

7. No local Gitea fallback during normal issue work

During normal author/coder workflows, do not read Gitea profile secret files.

Do not inspect or open files such as:

• profiles.json
• local token stores
• credential files
• local Gitea auth/profile config files
• .env files containing Gitea credentials
• keychain dumps
• token helper outputs

Do not run local Gitea helper scripts when MCP tools are available.

Use MCP tools for Gitea operations.

Local fallback is allowed only in explicit recovery mode when MCP is unavailable and identity/profile/capability can be independently proven.

If local fallback is used, report:

• why MCP was unavailable
• exact identity proof
• exact profile proof
• exact repo proof
• exact capability proof
• exact local command used

Do not use local fallback to bypass MCP gates.

8. Build a complete live issue inventory

List open issues according to the project’s issue selection policy.

Follow pagination until the tool proves there are no more pages.

Do not assume inventory is complete.

Do not claim next eligible issue, oldest eligible issue, or complete issue inventory unless pagination is proven.

Pagination proof must not rely on assumed default API page size.

Inventory is complete only if one of the following is proven:

• the MCP response explicitly says there is no next page / has_more=false / final page
• the workflow traversed pages until an empty page or explicit final page was returned
• the tool response includes total-count or pagination metadata proving all relevant issues were returned
• the request explicitly set page / limit / per_page, and the response explicitly proves the server honored that page size and did not truncate results

Do not say “inventory complete” merely because the result count is less than an assumed default page size.

For each candidate issue, identify:

• issue number
• title
• labels
• status
• author/requester, if relevant
• assignee/owner, if any
• linked PRs, if any
• dependency/blocker labels, if any
• whether it appears already claimed
• whether it appears already implemented or superseded
• whether it is eligible under project rules

Final report must include pagination/final-page proof.

9. Issue selection rules

State the issue ordering policy before selecting an issue.

If the project uses oldest-first, explicitly sort or reason by issue number or created date.

Do not rely on API response order unless the tool proves that order matches the project policy.

Do not pick:

• already-claimed issues
• issues assigned to another active worker
• issues with an open PR already covering the work
• duplicate issues
• blocked issues
• dependency-blocked issues
• already implemented issues
• issues outside the current requested scope
• process-hardening issues unless this run was explicitly started for process-hardening work
• reviewer-only issues if this is author/coder mode

For every earlier issue skipped, report:

• issue number
• current status
• blocking category
• proof used
• whether there is an open PR
• whether there is an active claim
• reason it is not eligible

If eligibility cannot be proven, classify it as:

ISSUE_ELIGIBILITY_UNVERIFIED

Then stop or produce a recovery handoff according to project policy.

Do not select an issue based only on memory from a previous session.

10. Linked PR / duplicate active work proof

Before claiming or working on an issue, check whether there is already an open PR, branch, or active claim for that issue.

If an open PR already exists for the issue, do not implement duplicate work.

Classify the issue as:

OPEN_PR_EXISTS

and skip it only if project policy allows skipping.

If branch naming or PR title convention links issues to branches, search for matching branches or PRs.

Report:

• issue number
• linked/open PRs found
• matching branches found, if checked
• active claims found
• duplicate work status

Do not create another branch/PR for the same issue unless the project explicitly allows taking over or updating existing work and exact capability is proven.

10A. Duplicate-work gate phases (#400)

Before any file edits, prove duplicate-work clearance with gitea_assess_work_issue_duplicate or gitea_lock_issue (which runs the same gate). The gate checks live:

• open PRs linked to the issue (head branch or Closes/Fixes reference),
• remote branches matching issue-<number>,
• active claim leases from structured heartbeats.

Re-check immediately before:

• gitea_commit_files (commit),
• branch push,
• gitea_create_pr (PR creation).

If a concurrent open PR appears after work begins:

• before commit/push → stop and preserve local work without pushing,
• after commit but before push → stop without pushing,
• after push but before PR creation → stop and produce a reconciliation handoff instead of opening a PR.

Final reports must state exactly one duplicate-work outcome:

• duplicate PR prevented
• duplicate branch prevented
• duplicate commit prevented
• duplicate work not prevented

11. Claim or lock the issue before implementation

Claim/lock the issue before implementation if the project provides a claim/lock mechanism.

If claim/lock requires a Gitea mutation, prove exact capability first.

If claim/lock fails, stop.

Do not implement unclaimed work.

If the claim/lock gates are broken, produce a recovery handoff.

Create a tooling issue only if this run is explicitly authorized to switch to issue-creation mode and exact create_issue capability is proven.

Report:

• claim mechanism used
• claim result
• claim timestamp, if available
• issue owner/assignee after claim, if available

12. Refresh stable branch before branch/worktree creation

Fetch the stable target branch from the remote before creating a task branch or worktree.

Do not rely on stale local master, main, or dev.

Record the fetched stable branch SHA.

If the stable branch cannot be fetched or verified, stop and produce a recovery handoff.

git fetch, git remote update, and any command that updates refs must be reported under Git ref mutations, not read-only diagnostics.

13. Branch and worktree ownership rule

Create a fresh session-owned worktree under branches/.

Prefer a branch name that includes the issue number, for example:

feat/issue-<ISSUE_NUMBER>-short-description

or:

fix/issue-<ISSUE_NUMBER>-short-description

Prefer a worktree path like:

branches/issue-<ISSUE_NUMBER>-short-description

Before any file edits, prove:

• project root
• current working directory
• main checkout branch
• stable branch
• stable branch SHA
• task branch name
• session-owned worktree path
• worktree path is inside branches/
• worktree is not the main checkout
• clean tracked state
• clean untracked state
• worktree HEAD/branch state

Do not reuse an existing worktree unless safe-reuse proof passes.

Safe-reuse proof must include:

• exact worktree path
• worktree is inside branches/
• worktree is not the main checkout
• worktree is not owned by another active task/session
• clean tracked state
• clean untracked state
• current branch/head before reset
• reset target SHA
• explicit project policy allowing reuse/reset

Do not run git reset --hard, git clean, checkout, or other destructive commands unless the worktree is session-owned or safe-reuse proof passes.

If safe-reuse proof cannot be produced, create a fresh session-owned worktree.

14. Implementation scope rule

Implement only what is required for the selected issue.

Do not perform opportunistic refactors.

Do not fix unrelated tests unless they are required for the selected issue and clearly documented.

Do not modify reviewer workflow files unless the selected issue explicitly requires workflow changes.

Do not modify Gitea profiles, MCP authorization, tokens, secrets, deployment config, production config, or credentials unless the selected issue explicitly requires it and exact capability/proof gates pass.

Do not introduce provenance markers, agent signatures, temporary files, debug dumps, or generated artifacts unless required.

If implementation uncovers a separate issue, note it in the final report or create a follow-up issue only if exact capability is proven and project policy allows it.

15. File edit rule

All edits must happen only inside the session-owned issue worktree.

Do not edit files in the main checkout.

Do not edit files in reviewer worktrees.

Do not edit unrelated worktrees.

Track every edited, created, deleted, or generated file.

If any file is edited, created, generated, or written, report it under File edits by author.

For each file write, report:

• exact path
• whether it was inside the repo
• whether it was tracked or untracked
• why it was created
• whether final git status was run after the write

Do not say File edits by author: none if any file write occurred.

Do not write files after the final clean-status check unless you rerun and report a new final clean-status check.

16. Validation rule

Run appropriate validation for the selected issue.

Validation may include:

• targeted tests
• full test suite
• compile checks
• lint checks
• type checks
• diff checks
• secret/provenance checks
• dangerous artifact checks
• project-specific validation

If validation cannot run, explain why and include the exact failure.

Do not hide failures.

Do not claim success if tests failed.

Do not skip required validation silently.

Do not bypass MCP gates.

Report every validation command with:

• exact command
• working directory
• exit code or pass/fail result
• summary count if available
• whether it was targeted, full-suite, compile, lint, diff, secret/provenance, or diagnostic validation

If using bare pytest, also report:

• which pytest
• pytest --version
• whether it resolves to the project venv

Prefer the project venv executable when available.

17. Baseline comparison rule

Do not run tests in the main checkout.

If the full suite fails and you need to prove failures are pre-existing, create a clean baseline worktree under branches/, such as:

branches/baseline-master-issue-<ISSUE_NUMBER>

Baseline comparison must include:

• baseline worktree path
• baseline target SHA
• task branch SHA
• exact command run on both worktrees
• baseline failures
• task branch failures
• proof the failure signatures match
• proof the baseline worktree was clean before and after validation
• proof the issue worktree was clean before and after validation

Do not claim “same as master” unless the clean baseline worktree proof is included.

Do not claim “full-suite failures are pre-existing” unless baseline proof is complete and the failure signatures match.

If full-suite failures differ or proof is incomplete, do not create a PR unless project policy explicitly allows PR creation with documented validation failures.

18. Pre-commit review

Before committing, review the actual diff.

Check:

• correctness
• tests
• scope
• security boundaries
• workflow rule compliance
• whether the implementation really satisfies the selected issue
• unrelated changes
• dangerous generated artifacts
• secrets
• provenance markers
• temporary agent files
• debug output
• formatting-only churn
• docs/tests consistency

Run:

• git status
• git diff --stat
• git diff
• project-required diff checks

Do not commit if unrelated or unsafe changes are present.

19. Commit rules

Commit only from the session-owned issue worktree.

Do not commit from the main checkout.

Commit only after implementation and required validation pass, unless project policy explicitly allows draft PRs with failing validation.

Commit message must reference the issue number.

Preferred format:

fix: short summary (Closes #<ISSUE_NUMBER>)

or:

feat: short summary (Closes #<ISSUE_NUMBER>)

Before commit, prove:

• worktree path
• branch name
• selected issue number
• staged files
• diff summary
• validation status

After commit, record:

• commit SHA
• commit message
• changed files

Do not amend, reset, rebase, squash, or force-push unless the project workflow explicitly allows it and the worktree is session-owned.

20. Push rules

Push only the session-owned task branch.

Do not push master, main, dev, tags, or unrelated branches.

Before push, prove:

• current branch
• upstream/remote target
• commit SHA being pushed
• selected issue number
• branch name matches the issue

After push, report:

• remote
• branch
• pushed commit SHA
• push result

If push fails, stop and produce a recovery handoff.

20A. Conflict-fix lease and push gate (#399)

When pushing to an existing PR branch to resolve merge conflicts:

1. Call gitea_acquire_conflict_fix_lease before any push.
2. Call gitea_assess_conflict_fix_push immediately before git push with:
   • branch head before push
   • branch head after push (local)
   • session worktree path
   • push cwd
   • whether the push is fast-forward
   • explicit remote, org, and repo when not using defaults
3. If assessment returns assessment_failed: true or pr_lookup: failed, stop and produce a recovery handoff with the structured reasons and resolved_repo fields — do not treat an MCP HTTP 500 as proof the push was unsafe or safe (#519).
4. Do not push when a reviewer holds an active lease on the same PR.
5. Do not force-push.
6. Do not push from the main checkout or wrong cwd.

Conflict-fix final reports must state:

• branch head before push
• branch head after push
• active reviewer lease status
• whether push was fast-forward
• whether any reviewer was active

21. PR creation rules

Create a PR only if implementation and validation pass, unless project policy explicitly allows draft PRs with documented validation failures.

Do not create a PR if:

• issue was not claimed/locked
• issue eligibility was unproven
• duplicate open PR exists
• task branch does not reference the issue
• implementation is incomplete
• validation failed without allowed exception
• worktree is dirty
• secrets/provenance/dangerous artifacts are present
• capability for PR creation is missing
• runtime context is blocked
• authenticated identity/profile changed unexpectedly

PR must reference or close the issue.

PR body must include:

• summary
• linked issue
• files changed
• validation commands and results
• risk
• exact worktree path
• branch name
• commit SHA
• known limitations, if any

Do not merge your own PR.

Do not approve your own PR.

Do not request changes on your own PR.

After PR creation, fetch or view the PR to verify:

• PR number
• PR URL
• PR title
• base branch
• head branch
• linked issue
• head SHA
• open status

22. Cleanup rules

Clean only session-owned temporary/baseline worktrees if the project workflow explicitly allows cleanup.

Do not delete unrelated branches/worktrees.

Do not delete the task worktree if the project expects it to remain for handoff unless policy says cleanup is allowed after PR creation.

Do not update the main checkout unless the canonical workflow explicitly allows it.

Any cleanup is a mutation and must be reported.

23. Recovery handoff rules

If blocked, produce a recovery handoff with:

• exact blocker
• failed tool/function, if any
• repo/project
• selected issue, if one was safely selected
• eligibility class
• claim/lock state
• branch name, if created
• worktree path, if created
• stable branch and stable branch SHA, if known
• files changed, if any
• validation state
• commit SHA, if committed
• PR number/URL, if created
• exact state reached before stopping
• safe next action
• statement that no unsafe mutation was attempted

Blocked handoffs must not include direct commit, push, or PR replay commands.

Blocked handoffs must say to rerun the full workflow after the blocker clears.

24. Final report must be precise

Include:

• canonical workflow source/version/hash, if available
• authenticated identity/profile
• repo/project
• capability proof summary
• issue inventory proof, including pagination/final-page proof
• issue ordering policy used
• selected issue number/title
• eligibility class
• skipped earlier issues and proof, if any
• duplicate active work proof
• claim/lock result
• stable branch and stable branch SHA
• branch name
• worktree path
• worktree inside branches/: true/false
• worktree branch/HEAD state
• worktree dirty before implementation: true/false
• files changed
• validation commands and results
• baseline comparison result, if used
• pre-commit diff review result
• commit SHA and commit message, if committed
• push result, if pushed
• PR number and URL, if created
• PR verification result, if created
• cleanup result
• blockers, if stopped
• confirmation that the main checkout was not used for task work

If the report and actual tool/command log disagree, fix the report before final output.

25. Final report must distinguish mutation types

Do not use the legacy field Workspace mutations.

Use only precise categories:

• File edits by author:
• Worktree/index mutations:
• Git ref mutations:
• MCP/Gitea mutations:
• Issue mutations:
• Branch mutations:
• Commit mutations:
• Push mutations:
• PR mutations:
• Cleanup mutations:
• External-state mutations:
• Read-only diagnostics:

Issue-lock file (/tmp/gitea_issue_lock.json) read/write/delete is always an external-state mutation. Never claim External-state mutations: none after seeding, restoring, or removing that file. Manual lock seeding is not a normal recovery path (#447); use gitea_lock_issue or the #442 adoption recovery path instead. Link broader redesign: #438.

git fetch, git remote update, and any command that updates refs must be listed under Git ref mutations, not read-only diagnostics.

If git reset --hard, checkout, clean, worktree add/remove, merge simulation, merge abort, or similar commands occurred, report them under Worktree/index mutations.

Use precise wording:

• File edits by author: none
• Worktree/index mutations: ...
• Git ref mutations: ...
• MCP/Gitea mutations: ...

Do not collapse issue, branch, commit, push, PR, cleanup, or external-state mutations into vague wording.

26. Forbidden final-report claims unless proven

Do not claim:

• next eligible issue
• oldest eligible issue
• issue claimed
• no duplicate work
• no open PR
• worktree clean
• validation passed
• same as master
• full-suite failures are pre-existing
• committed
• pushed
• PR created
• issue closed
• main checkout untouched
• no file edits
• no unsafe mutation
• all gates passed
• target branch up to date

unless the corresponding proof is included.

If anything blocks safe work or PR creation, stop immediately and produce an executable recovery handoff.

Do not improvise around the gates.

27. Proof wording enforcement

The following phrases are forbidden unless directly supported by current-session evidence:

• next eligible issue
• oldest eligible issue
• inventory complete
• no duplicate work
• issue claimed
• worktree clean
• validation passed
• same as master
• full-suite failures are pre-existing
• committed
• pushed
• PR created
• issue closed
• target branch up to date
• all gates passed
• no unsafe mutation
• no file edits

If the proof comes from prior state rather than a command/tool run in the current session, label it as prior proof, not live proof.

If a tool call was rejected, confirmation-gated, dry-run-only, or no-op, report it separately from performed mutations.

28. Final self-check before output

Before final output, check the report for contradictions.

Verify:

• if any file was edited, File edits by author is not none
• if any worktree was added/removed, Worktree/index mutations lists it
• if any fetch happened, Git ref mutations lists it
• if any issue was claimed/commented/updated, Issue mutations lists it
• if any branch was created, Branch mutations lists it
• if any commit was created, Commit mutations lists it
• if any push occurred, Push mutations lists it
• if any PR was created, PR mutations lists it
• if any cleanup happened, Cleanup mutations lists it
• if any issue/PR external state changed, External-state mutations lists it
• if pagination is claimed complete, final-page proof is present
• if same-as-master is claimed, baseline proof is complete
• if selected issue is claimed next eligible, every earlier issue has proof-backed skip reasoning
• if PR created is claimed, PR verification proof is present
• if main checkout untouched is claimed, main checkout status proof is present

If any contradiction exists, fix the final report before output.

29. Controller handoff schema

End every run with a controller handoff using this schema.

Do not omit fields. Use none or not verified in this session where appropriate.

Controller Handoff:

• Task:
• Repo:
• Role:
• Identity:
• Active profile:
• Runtime context:
• Selected issue:
• Eligibility class:
• Issue ordering policy:
• Issue inventory pagination proof:
• Earlier issues skipped:
• Duplicate active work proof:
• Claim/lock state:
• Stable branch:
• Stable branch SHA:
• Branch name:
• Worktree path:
• Worktree inside branches:
• Worktree branch/HEAD state:
• Worktree dirty before implementation:
• Files changed:
• Validation:
• Baseline comparison:
• Commit SHA:
• Push result:
• PR number:
• PR URL:
• PR verification:
• Main checkout branch:
• Main checkout dirty state:
• Main checkout used for task work:
• File edits by author:
• Worktree/index mutations:
• Git ref mutations:
• MCP/Gitea mutations:
• Issue mutations:
• Branch mutations:
• Commit mutations:
• Push mutations:
• PR mutations:
• Cleanup mutations:
• External-state mutations:
• Read-only diagnostics:
• Blockers:
• Current status:
• Safe next action:
• Safety statement:

30. Stop conditions summary

Stop immediately and produce a recovery handoff if:

• canonical workflow is required but cannot be loaded
• identity/profile/capability cannot be proven
• runtime context is blocked
• infra stop appears
• MCP reconnect fails
• capability state is stale
• issue inventory pagination cannot be proven
• issue ordering cannot be proven
• issue eligibility cannot be proven
• duplicate active work cannot be checked
• selected issue is already claimed by another worker
• selected issue already has an open PR
• claim/lock fails
• stable branch cannot be fetched
• task worktree cannot be created safely
• task worktree is dirty before implementation
• validation cannot run
• validation fails without allowed exception
• baseline comparison is required but incomplete
• diff review finds unrelated or unsafe changes
• commit fails
• push fails
• PR creation fails
• PR verification fails
• any report contradiction cannot be resolved

Blocked handoffs must not include direct commit, push, or PR replay commands.

Blocked handoffs must say to rerun the full workflow after the blocker clears.

Do not improvise around the gates.