docs: split LLM project workflow into task-specific modes (Closes #333)
Consolidate all four canonical workflow files and router SKILL.md: - review-merge-pr.md (from #334 canonical prompt) - reconcile-landed-pr.md (reconciliation gates + handoff schema) - create-issue.md (canonical issue-creation prompt) - work-issue.md (canonical author/coder prompt) SKILL.md is now a short router with mode isolation and universal rules. Adds final-report schemas for all modes and 13 doc-contract tests. Supersedes partial split work in PR #335; full #333 acceptance in one PR.
This commit is contained in:
@@ -0,0 +1,666 @@
|
||||
---
|
||||
task_mode: create-issue
|
||||
canonical: true
|
||||
final_report_schema: ../schemas/create-issue-final-report.md
|
||||
---
|
||||
|
||||
# Create issue workflow (canonical)
|
||||
|
||||
**Task mode:** `create-issue`
|
||||
|
||||
This file is the canonical issue-creation workflow for Gitea-Tools. Load it
|
||||
before any issue mutation. Final report schema:
|
||||
[`schemas/create-issue-final-report.md`](../schemas/create-issue-final-report.md).
|
||||
|
||||
**Default task prompt:**
|
||||
|
||||
> Create or update Gitea issues in this project only if every identity,
|
||||
> capability, duplicate-search, issue-scope, final-report, mutation-ledger,
|
||||
> and proof-wording gate passes.
|
||||
|
||||
Do not improvise around the gates. Follow project skills, MCP gates, and
|
||||
workflow rules exactly.
|
||||
|
||||
This is an issue-creation workflow. It is not a reviewer workflow and not an
|
||||
implementation workflow.
|
||||
|
||||
---
|
||||
|
||||
## 0. Load the canonical workflow first
|
||||
|
||||
Before starting issue creation or issue update work, check whether the project provides a canonical create-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 `create-issue` mode only.
|
||||
|
||||
Do not:
|
||||
|
||||
* review PRs
|
||||
* approve PRs
|
||||
* request changes
|
||||
* merge PRs
|
||||
* close PRs
|
||||
* close issues unless the user explicitly asks and exact close capability is proven
|
||||
* implement code
|
||||
* edit repo files
|
||||
* create branches
|
||||
* create commits
|
||||
* push branches
|
||||
* create PRs
|
||||
* run tests unless the canonical workflow explicitly requires validation for issue creation
|
||||
* perform reviewer-only actions
|
||||
* perform author/coder-only actions
|
||||
* perform MCP repair
|
||||
|
||||
If the task requires review, merge, issue implementation, 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 profile
|
||||
* repo/project
|
||||
* runtime context
|
||||
* exact capability for reading/searching issues
|
||||
* exact capability for creating issues, if creating issues
|
||||
* exact capability for commenting on issues, if commenting on existing issues
|
||||
* exact capability for editing issues, if editing existing issues
|
||||
* exact capability for applying labels, if applying labels
|
||||
* exact capability for assigning issues, if assigning issues
|
||||
* exact capability for closing issues, only if explicitly requested
|
||||
|
||||
A nearby capability does not count.
|
||||
|
||||
Examples:
|
||||
|
||||
* `create_issue` does not authorize `issue_comment`
|
||||
* `issue_comment` does not authorize `create_issue`
|
||||
* `create_pr` does not authorize `create_issue`
|
||||
* `review_pr` does not authorize `create_issue`
|
||||
* `merge_pr` does not authorize `issue_comment`
|
||||
* `gitea.read` does not authorize creating, commenting, editing, labeling, assigning, or closing issues
|
||||
|
||||
If exact capability cannot be proven, stop and produce a recovery handoff only.
|
||||
|
||||
## 3. Stop immediately on blocked infrastructure
|
||||
|
||||
If any of the following appears, stop immediately:
|
||||
|
||||
* `infra_stop`
|
||||
* MCP reconnect failure
|
||||
* stale capability state
|
||||
* missing capability
|
||||
* workspace mismatch
|
||||
* dirty control checkout, if the canonical workflow treats that as blocking
|
||||
* 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 duplicate search, issue creation, issue commenting, issue editing, labeling, assignment, or cleanup.
|
||||
|
||||
Produce an executable recovery handoff only.
|
||||
|
||||
Blocked recovery handoffs must not include direct issue-create or issue-comment replay commands.
|
||||
|
||||
Blocked handoffs must say to rerun the full workflow after the blocker clears.
|
||||
|
||||
## 4. Main checkout rule
|
||||
|
||||
This workflow should not mutate repo files.
|
||||
|
||||
Do not edit files in the main checkout.
|
||||
|
||||
Do not create branches.
|
||||
|
||||
Do not create commits.
|
||||
|
||||
Do not push.
|
||||
|
||||
Do not run implementation work.
|
||||
|
||||
Do not run reviewer validation.
|
||||
|
||||
Reading repository files is allowed only when needed to understand the requested issue and only if the canonical workflow permits it.
|
||||
|
||||
If the main checkout is dirty and the project treats dirty control checkout as blocking, stop and produce a recovery handoff.
|
||||
|
||||
## 5. No raw MCP repair during issue creation
|
||||
|
||||
Do not run `pkill`, kill MCP processes, edit MCP config, restart servers, or perform control-checkout repair during issue creation.
|
||||
|
||||
If MCP repair is required, stop issue creation and produce a separate `CONTROL-CHECKOUT REPAIR MODE` handoff.
|
||||
|
||||
Do not mix MCP repair mode with create-issue mode.
|
||||
|
||||
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 creation.
|
||||
|
||||
Use direct commands and MCP tools only.
|
||||
|
||||
If a required action cannot complete synchronously, stop and produce a recovery handoff.
|
||||
|
||||
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 creation
|
||||
|
||||
During normal issue-creation 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. Understand the requested issue work
|
||||
|
||||
Before searching or creating issues, restate the requested issue-creation task in operational terms.
|
||||
|
||||
Identify:
|
||||
|
||||
* target repo/project
|
||||
* issue topic
|
||||
* issue type, if known
|
||||
* whether this is a new issue, duplicate check, issue update, or issue-comment task
|
||||
* whether the user provided exact title/body text
|
||||
* whether acceptance criteria were provided
|
||||
* whether multiple issues are requested
|
||||
* whether labels, assignees, milestones, or links are requested
|
||||
* whether any requested action requires capability beyond issue creation
|
||||
|
||||
Do not invent missing requirements.
|
||||
|
||||
If the request is ambiguous but safe to proceed, make a reasonable best-effort issue with clear assumptions.
|
||||
|
||||
If ambiguity would cause unsafe or wrong mutation, stop and ask for clarification or produce a recovery handoff according to project policy.
|
||||
|
||||
## 9. Duplicate search before mutation
|
||||
|
||||
Before creating any issue, search open and closed issues for duplicates.
|
||||
|
||||
Duplicate search must happen before each issue creation unless a batch search clearly covers all proposed issues.
|
||||
|
||||
Search terms must include:
|
||||
|
||||
* exact proposed issue title
|
||||
* key noun phrase from the problem
|
||||
* key workflow/tool name
|
||||
* key failure phrase or error phrase
|
||||
* likely alternate wording
|
||||
* linked PR number, issue number, or file name, if relevant
|
||||
|
||||
If the user supplied search terms, use those too.
|
||||
|
||||
For each proposed issue, report:
|
||||
|
||||
* search terms used
|
||||
* matching issue numbers/titles
|
||||
* whether each match is open or closed
|
||||
* whether any match fully covers the requested issue
|
||||
* whether any match partially covers the requested issue
|
||||
* whether a new issue is still needed
|
||||
|
||||
Do not create a duplicate issue if an existing issue fully covers the problem.
|
||||
|
||||
If a duplicate exists and fully covers the problem, stop issue creation for that topic and report the duplicate.
|
||||
|
||||
If a duplicate exists but is missing important acceptance criteria, comment on the existing issue only if exact `issue_comment` capability is proven and the user/task authorizes commenting.
|
||||
|
||||
If commenting is not authorized, report the existing issue and the missing criteria in the final handoff.
|
||||
|
||||
## 10. Issue inventory pagination rule
|
||||
|
||||
If listing/searching issues returns paginated results, follow pagination until the tool proves there are no more pages.
|
||||
|
||||
Do not assume search results or issue inventory are complete.
|
||||
|
||||
Pagination proof must not rely on assumed default API page size.
|
||||
|
||||
Search/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 “duplicate search complete” merely because the result count is less than an assumed default page size.
|
||||
|
||||
If pagination metadata is absent and the tool cannot page, report `ISSUE_SEARCH_PAGINATION_UNPROVEN`.
|
||||
|
||||
If duplicate search cannot be trusted, do not create the issue unless the canonical workflow explicitly permits best-effort issue creation with that limitation disclosed.
|
||||
|
||||
## 11. Issue creation scope rule
|
||||
|
||||
Create only issues within the requested scope.
|
||||
|
||||
Do not create extra issues just because related problems are noticed.
|
||||
|
||||
Do not create process-hardening issues unless the user explicitly requested process-hardening or the current task is explicitly about workflow/tooling gaps.
|
||||
|
||||
Do not create implementation issues during reviewer mode.
|
||||
|
||||
Do not create reviewer issues during work-on-issue mode.
|
||||
|
||||
Do not create issues in a different repository unless the user explicitly asked and exact capability is proven.
|
||||
|
||||
If multiple issues are requested, create only the requested issues and only after duplicate search for each one.
|
||||
|
||||
If a proposed issue is too broad, split it only if the user requested splitting or the canonical workflow requires issue granularity.
|
||||
|
||||
## 12. Issue content quality rule
|
||||
|
||||
Every created issue must be actionable.
|
||||
|
||||
Include, when applicable:
|
||||
|
||||
* title
|
||||
* problem statement
|
||||
* observed evidence
|
||||
* expected behavior
|
||||
* required behavior
|
||||
* acceptance criteria
|
||||
* affected workflow/tool/files
|
||||
* safety or security considerations
|
||||
* duplicate search summary
|
||||
* related issues or PRs
|
||||
* non-goals, if useful
|
||||
|
||||
Acceptance criteria must be concrete and testable.
|
||||
|
||||
Avoid vague issues like:
|
||||
|
||||
* “make workflow better”
|
||||
* “fix LLM behavior”
|
||||
* “improve process”
|
||||
* “handle this better”
|
||||
|
||||
Instead, describe the exact wall, gate, verifier, test, schema, helper, or prompt change required.
|
||||
|
||||
## 13. Issue title rule
|
||||
|
||||
Use concise, specific titles.
|
||||
|
||||
Good title patterns:
|
||||
|
||||
* `Enforce <specific gate>`
|
||||
* `Add verifier for <specific report/proof problem>`
|
||||
* `Split <large workflow> into <specific components>`
|
||||
* `Block <unsafe action> during <workflow mode>`
|
||||
* `Require <proof type> before <claim/action>`
|
||||
|
||||
Avoid titles that are too broad or emotional.
|
||||
|
||||
The title should be unique enough that duplicate search can find it later.
|
||||
|
||||
## 14. Issue body rule
|
||||
|
||||
Issue body must include the full acceptance criteria.
|
||||
|
||||
Do not create placeholder issues.
|
||||
|
||||
Do not create issues with only a title unless the user explicitly requested title-only creation.
|
||||
|
||||
If the user supplied exact issue body text, preserve it unless it contains unsafe instructions, stale facts, or contradictions.
|
||||
|
||||
If edits are needed, make the smallest correction necessary and report the correction.
|
||||
|
||||
Do not silently change requested meaning.
|
||||
|
||||
## 15. Labels, assignees, and metadata
|
||||
|
||||
Apply labels, assignees, milestones, or project fields only if:
|
||||
|
||||
* the user requested them, or
|
||||
* the canonical workflow requires them, and
|
||||
* exact capability is proven.
|
||||
|
||||
Do not guess labels if project label policy is unknown.
|
||||
|
||||
If labels are useful but capability or policy is unclear, mention recommended labels in the final report instead of applying them.
|
||||
|
||||
Do not assign issues to people unless explicitly requested or required by project workflow.
|
||||
|
||||
## 16. Comment-on-existing issue rule
|
||||
|
||||
Comment on an existing issue only if:
|
||||
|
||||
* an existing issue partially covers the requested work, or
|
||||
* the user asked to add information to an existing issue, or
|
||||
* the canonical workflow requires duplicate consolidation comments, and
|
||||
* exact `issue_comment` capability is proven.
|
||||
|
||||
Comment must be specific and useful.
|
||||
|
||||
Include:
|
||||
|
||||
* why the existing issue is relevant
|
||||
* what acceptance criteria or evidence should be added
|
||||
* whether this avoids creating a duplicate
|
||||
|
||||
Do not comment just to say “duplicate found” unless the project workflow requires it.
|
||||
|
||||
Do not close duplicate issues unless explicitly requested and exact close capability is proven.
|
||||
|
||||
## 17. No hidden mutations
|
||||
|
||||
Do not perform unreported mutations.
|
||||
|
||||
Every issue creation, issue comment, issue edit, label change, assignment, milestone change, close/reopen action, or external-state change must be reported.
|
||||
|
||||
If a tool call is dry-run-only, confirmation-gated, rejected, or no-op, report it separately from performed mutations.
|
||||
|
||||
A dry run is not a mutation.
|
||||
|
||||
A rejected call is not a performed mutation.
|
||||
|
||||
A successful issue creation is an issue mutation.
|
||||
|
||||
A successful issue comment is an issue mutation.
|
||||
|
||||
A successful label/assignment/milestone update is an issue mutation or external-state mutation.
|
||||
|
||||
## 18. Issue creation gate
|
||||
|
||||
Before creating each issue, verify:
|
||||
|
||||
* identity is still valid
|
||||
* active profile is still valid
|
||||
* runtime context is still safe
|
||||
* exact `create_issue` capability is still valid
|
||||
* duplicate search was completed or limitation was explicitly allowed
|
||||
* proposed title is not a duplicate
|
||||
* proposed body includes actionable acceptance criteria
|
||||
* target repo is correct
|
||||
* no mode switch has occurred
|
||||
|
||||
If any gate fails, do not create the issue.
|
||||
|
||||
Produce a recovery handoff or duplicate report.
|
||||
|
||||
## 19. Issue commenting gate
|
||||
|
||||
Before commenting on an existing issue, verify:
|
||||
|
||||
* identity is still valid
|
||||
* active profile is still valid
|
||||
* runtime context is still safe
|
||||
* exact `issue_comment` capability is still valid
|
||||
* target issue number is correct
|
||||
* comment body is specific and useful
|
||||
* comment will not duplicate an existing comment
|
||||
* no mode switch has occurred
|
||||
|
||||
If any gate fails, do not comment.
|
||||
|
||||
Produce a recovery handoff or report the intended comment as a recommendation only.
|
||||
|
||||
## 20. Issue edit/update gate
|
||||
|
||||
Before editing an existing issue, verify:
|
||||
|
||||
* identity is still valid
|
||||
* active profile is still valid
|
||||
* runtime context is still safe
|
||||
* exact edit capability is still valid
|
||||
* target issue number is correct
|
||||
* update is explicitly requested or required by canonical workflow
|
||||
* update does not erase useful existing content
|
||||
* no mode switch has occurred
|
||||
|
||||
If any gate fails, do not edit.
|
||||
|
||||
Prefer commenting over editing unless the user explicitly requested an edit or the canonical workflow requires issue body updates.
|
||||
|
||||
## 21. Final report must be precise
|
||||
|
||||
Include:
|
||||
|
||||
* canonical workflow source/version/hash, if available
|
||||
* authenticated identity/profile
|
||||
* repo/project
|
||||
* runtime context summary
|
||||
* exact capability proof summary
|
||||
* requested issue-creation task
|
||||
* duplicate search terms used
|
||||
* duplicate search result
|
||||
* pagination/final-page proof for issue search, if applicable
|
||||
* issues created, with issue numbers and URLs
|
||||
* existing issues commented, with issue numbers and URLs
|
||||
* existing issues edited, with issue numbers and URLs
|
||||
* issues skipped as duplicates, with issue numbers and titles
|
||||
* labels/assignees/milestones applied, if any
|
||||
* blockers, if stopped
|
||||
* confirmation that no PR review, approval, request-changes, merge, branch, checkout, commit, push, or repo-file mutation was performed
|
||||
|
||||
If the report and actual tool/command log disagree, fix the report before final output.
|
||||
|
||||
## 22. Final report must distinguish mutation types
|
||||
|
||||
Do not use the legacy field `Workspace mutations`.
|
||||
|
||||
Use only precise categories:
|
||||
|
||||
* File edits by issue creator:
|
||||
* Worktree/index mutations:
|
||||
* Git ref mutations:
|
||||
* MCP/Gitea mutations:
|
||||
* Issue mutations:
|
||||
* Label/assignment/milestone mutations:
|
||||
* External-state mutations:
|
||||
* Read-only diagnostics:
|
||||
|
||||
Use precise wording:
|
||||
|
||||
* `File edits by issue creator: none`
|
||||
* `Worktree/index mutations: none`
|
||||
* `Git ref mutations: none`
|
||||
* `Issue mutations: ...`
|
||||
|
||||
If no repo files were edited, say:
|
||||
|
||||
`File edits by issue creator: none`
|
||||
|
||||
If no branches/worktrees were touched, say:
|
||||
|
||||
`Worktree/index mutations: none`
|
||||
|
||||
If no git refs were updated, say:
|
||||
|
||||
`Git ref mutations: none`
|
||||
|
||||
Do not hide issue mutations inside vague `MCP/Gitea mutations`.
|
||||
|
||||
## 23. Local artifact and report consistency rule
|
||||
|
||||
Do not create local walkthrough, notes, markdown, JSON, or report artifacts during issue-creation runs unless the canonical workflow or operator explicitly requires it.
|
||||
|
||||
If any file is edited, created, generated, or written, report it under `File edits by issue creator`.
|
||||
|
||||
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 status was checked after the write
|
||||
|
||||
Do not say `File edits by issue creator: 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.
|
||||
|
||||
Default behavior: do not create local artifacts during issue creation.
|
||||
|
||||
## 24. Forbidden final-report claims unless proven
|
||||
|
||||
Do not claim:
|
||||
|
||||
* `duplicate search complete`
|
||||
* `no duplicate found`
|
||||
* `issue created`
|
||||
* `issue commented`
|
||||
* `issue updated`
|
||||
* `label applied`
|
||||
* `capability proven`
|
||||
* `runtime safe`
|
||||
* `all gates passed`
|
||||
* `no file edits`
|
||||
* `no unsafe mutation`
|
||||
* `no PR mutation`
|
||||
* `no repo mutation`
|
||||
* `pagination complete`
|
||||
* `final page`
|
||||
* `no next page`
|
||||
|
||||
unless the corresponding proof is included.
|
||||
|
||||
If anything blocks safe issue creation or issue update, stop immediately and produce an executable recovery handoff.
|
||||
|
||||
Do not improvise around the gates.
|
||||
|
||||
## 25. Proof wording enforcement
|
||||
|
||||
The following phrases are forbidden unless directly supported by current-session evidence:
|
||||
|
||||
* duplicate search complete
|
||||
* no duplicate found
|
||||
* issue created
|
||||
* issue commented
|
||||
* issue updated
|
||||
* labels applied
|
||||
* capability proven
|
||||
* runtime safe
|
||||
* all gates passed
|
||||
* no file edits
|
||||
* no unsafe mutation
|
||||
* no PR mutation
|
||||
* no repo mutation
|
||||
* pagination complete
|
||||
* final page
|
||||
* no next page
|
||||
|
||||
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.
|
||||
|
||||
## 26. Final self-check before output
|
||||
|
||||
Before final output, check the report for contradictions.
|
||||
|
||||
Verify:
|
||||
|
||||
* if any file was edited, `File edits by issue creator` 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 created, `Issue mutations` lists it
|
||||
* if any issue was commented, `Issue mutations` lists it
|
||||
* if any issue was edited, `Issue mutations` lists it
|
||||
* if any labels/assignees/milestones were changed, the correct mutation category lists it
|
||||
* if duplicate search is claimed complete, pagination/final-page proof is present or limitation is disclosed
|
||||
* if no duplicate is claimed, search terms and results are present
|
||||
* if issue created is claimed, issue number and URL are present
|
||||
* if no PR mutation is claimed, no PR tool/action was used
|
||||
* if no repo mutation is claimed, no branch/worktree/file/commit/push action occurred
|
||||
* if all gates passed is claimed, every required gate has proof
|
||||
|
||||
If any contradiction exists, fix the final report before output.
|
||||
|
||||
## 27. 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:
|
||||
* Requested issue task:
|
||||
* Workflow source:
|
||||
* Capability proof:
|
||||
* Duplicate search terms:
|
||||
* Duplicate search pagination proof:
|
||||
* Duplicates found:
|
||||
* Issues created:
|
||||
* Issues commented:
|
||||
* Issues edited:
|
||||
* Issues skipped as duplicates:
|
||||
* Labels/assignees/milestones changed:
|
||||
* File edits by issue creator:
|
||||
* Worktree/index mutations:
|
||||
* Git ref mutations:
|
||||
* MCP/Gitea mutations:
|
||||
* Issue mutations:
|
||||
* Label/assignment/milestone mutations:
|
||||
* External-state mutations:
|
||||
* Read-only diagnostics:
|
||||
* Blockers:
|
||||
* Current status:
|
||||
* Safe next action:
|
||||
* Safety statement:
|
||||
|
||||
## 28. 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
|
||||
* duplicate search cannot be performed and best-effort creation is not allowed
|
||||
* issue search pagination cannot be proven and best-effort creation is not allowed
|
||||
* duplicate fully covers the requested issue
|
||||
* requested issue body is unsafe or not actionable
|
||||
* target repo cannot be proven
|
||||
* create_issue capability is missing
|
||||
* issue_comment capability is missing for a required comment
|
||||
* issue edit capability is missing for a required edit
|
||||
* mode switch would be required
|
||||
* any report contradiction cannot be resolved
|
||||
|
||||
Blocked handoffs must not include direct issue-create or issue-comment replay commands.
|
||||
|
||||
Blocked handoffs must say to rerun the full workflow after the blocker clears.
|
||||
|
||||
Do not improvise around the gates.
|
||||
@@ -0,0 +1,387 @@
|
||||
---
|
||||
task_mode: reconcile-landed-pr
|
||||
canonical: true
|
||||
final_report_schema: ../schemas/reconcile-landed-final-report.md
|
||||
---
|
||||
|
||||
# Reconcile already-landed open PR workflow (canonical)
|
||||
|
||||
**Task mode:** `reconcile-landed-pr`
|
||||
|
||||
This file is the canonical reconciliation workflow for open PRs whose head SHA
|
||||
is already an ancestor of the target branch. Load it before any reconciliation
|
||||
mutation. Final report schema:
|
||||
[`schemas/reconcile-landed-final-report.md`](../schemas/reconcile-landed-final-report.md).
|
||||
|
||||
**Default task prompt:**
|
||||
|
||||
> Reconcile already-landed open PRs in this project. Do not review or merge
|
||||
> normal PRs. Close or comment only when exact capability is proven.
|
||||
|
||||
Do not improvise around the gates. Follow project skills, MCP gates, and
|
||||
workflow rules exactly.
|
||||
|
||||
This is a reconciliation workflow. It is not a normal PR review/merge workflow.
|
||||
|
||||
---
|
||||
|
||||
## 0. Load the canonical workflow first
|
||||
|
||||
Before starting reconciliation work, check whether the project provides a
|
||||
canonical reconcile-landed-PR 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 `reconcile-landed-pr` mode only.
|
||||
|
||||
**Do not review or merge normal PRs.**
|
||||
|
||||
Do not:
|
||||
|
||||
* approve PRs
|
||||
* request changes on PRs
|
||||
* merge PRs
|
||||
* implement code
|
||||
* edit repo files
|
||||
* create branches
|
||||
* create commits
|
||||
* push branches
|
||||
* create PRs
|
||||
* run normal PR validation as review approval input
|
||||
* perform author/coder implementation work
|
||||
* perform raw MCP repair
|
||||
|
||||
If the task requires review, merge, issue implementation, 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 profile (reconciler or author with close capabilities, as required)
|
||||
* repo/project
|
||||
* runtime context
|
||||
* exact capability for reading/listing PRs and issues
|
||||
* exact capability for PR inspect (`gitea.read` / view PR)
|
||||
* exact capability for issue inspect
|
||||
* exact capability for PR comment, if commenting
|
||||
* exact capability for issue comment, if commenting
|
||||
* exact capability for PR close, if closing PRs
|
||||
* exact capability for issue close, if closing issues
|
||||
|
||||
A nearby capability does not count.
|
||||
|
||||
Examples:
|
||||
|
||||
* `review_pr` does not authorize PR close
|
||||
* `merge_pr` does not authorize PR close or issue close
|
||||
* `create_issue` does not authorize `issue_comment`
|
||||
* `issue_comment` does not authorize PR close
|
||||
* `gitea.read` does not authorize close or comment mutations
|
||||
|
||||
If exact capability cannot be proven, stop and produce a recovery handoff only.
|
||||
|
||||
## 3. Stop immediately on blocked infrastructure
|
||||
|
||||
If any of the following appears, stop immediately:
|
||||
|
||||
* `infra_stop`
|
||||
* MCP reconnect failure
|
||||
* stale capability state
|
||||
* missing capability
|
||||
* workspace mismatch
|
||||
* 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 inventory, ancestry proof, commenting, closing, or cleanup.
|
||||
|
||||
Produce an executable recovery handoff only.
|
||||
|
||||
Blocked recovery handoffs must not include direct close or comment replay
|
||||
commands.
|
||||
|
||||
Blocked handoffs must say to rerun the full workflow after the blocker clears.
|
||||
|
||||
## 4. Main checkout rule
|
||||
|
||||
This workflow should not mutate repo files.
|
||||
|
||||
Do not edit files in the main checkout.
|
||||
|
||||
Do not create branches, commits, or pushes.
|
||||
|
||||
Do not run implementation or reviewer validation worktrees for code edits.
|
||||
|
||||
Reading repository files is allowed only when needed to understand
|
||||
reconciliation scope and only if this workflow permits it.
|
||||
|
||||
## 5. No raw MCP repair during reconciliation
|
||||
|
||||
Do not run `pkill`, kill MCP processes, edit MCP config, restart servers, or
|
||||
perform control-checkout repair during reconciliation.
|
||||
|
||||
If MCP repair is required, stop and produce a separate `CONTROL-CHECKOUT REPAIR
|
||||
MODE` handoff.
|
||||
|
||||
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 reconciliation.
|
||||
|
||||
Use direct commands and MCP tools only.
|
||||
|
||||
If a required action cannot complete synchronously, stop and produce a recovery
|
||||
handoff.
|
||||
|
||||
## 7. No local Gitea fallback during normal reconciliation
|
||||
|
||||
During normal reconciliation workflows, do not read Gitea profile secret files.
|
||||
|
||||
Do not inspect `profiles.json`, local token stores, credential files, `.env`
|
||||
Gitea credentials, keychain dumps, or 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.
|
||||
|
||||
## 8. Build a complete live open PR inventory
|
||||
|
||||
List open PRs for the target repo according to project policy.
|
||||
|
||||
Follow pagination until the tool proves there are no more pages.
|
||||
|
||||
Do not assume inventory is complete.
|
||||
|
||||
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 PRs 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
|
||||
|
||||
If pagination cannot be proven, report `INVENTORY_PAGINATION_UNPROVEN` and stop
|
||||
unless project policy allows best-effort reconciliation with that limitation
|
||||
disclosed.
|
||||
|
||||
## 9. Already-landed proof
|
||||
|
||||
For each candidate PR, prove whether the PR head SHA is already landed on the
|
||||
target branch.
|
||||
|
||||
**Already-landed proof** must include:
|
||||
|
||||
* PR number and title
|
||||
* candidate head SHA (full 40-hex)
|
||||
* target branch name
|
||||
* target branch SHA (full 40-hex) after fetch
|
||||
* ancestor proof method (`git merge-base --is-ancestor`, equivalent forge API, or
|
||||
documented project helper)
|
||||
* ancestor proof result (true/false)
|
||||
* live PR state (open/closed, merged flag)
|
||||
|
||||
Do not classify a PR as already-landed without live ancestor proof.
|
||||
|
||||
If ancestry cannot be proven, classify as `ANCESTRY_UNPROVEN` and skip close
|
||||
mutations.
|
||||
|
||||
## 10. Linked issue live verification
|
||||
|
||||
If the PR claims to close or link an issue, fetch the linked issue live before
|
||||
reporting its status.
|
||||
|
||||
If the linked issue was not fetched live in the current session, report:
|
||||
|
||||
`Linked issue status: not verified in this session`
|
||||
|
||||
Do not claim `issue open`, `issue closed`, or `issue resolved` without live
|
||||
proof.
|
||||
|
||||
## 11. Reconciliation selection rules
|
||||
|
||||
Select PRs eligible for reconciliation:
|
||||
|
||||
* open PR state
|
||||
* `merged=false` unless project policy says otherwise
|
||||
* head SHA is ancestor of target branch (already-landed proof passed)
|
||||
* not selected for normal review/merge in this run
|
||||
|
||||
Eligibility class for selected PRs: `ALREADY_LANDED_RECONCILE_REQUIRED`
|
||||
|
||||
Do not select PRs that fail already-landed proof for normal review/merge
|
||||
treatment in this mode.
|
||||
|
||||
## 12. Reconciliation comment policy
|
||||
|
||||
Post a reconciliation comment only if:
|
||||
|
||||
* exact PR-comment or issue-comment capability is proven
|
||||
* the comment adds durable evidence (ancestor proof summary, recommended close
|
||||
action, linked issue status)
|
||||
* the comment will not duplicate an equivalent recent reconciliation comment
|
||||
|
||||
If comment capability is missing, record the intended comment in the final
|
||||
handoff only.
|
||||
|
||||
## 13. PR close rules
|
||||
|
||||
Close a PR only if:
|
||||
|
||||
* already-landed proof passed in this session
|
||||
* exact PR-close capability is proven
|
||||
* PR is still open at mutation time (live re-fetch)
|
||||
* head SHA still matches the proved candidate head SHA
|
||||
|
||||
If PR-close capability is missing, produce a recovery handoff with exact PR,
|
||||
proof, and required capability. Do not loop forever re-blocking the reviewer
|
||||
queue.
|
||||
|
||||
## 14. Issue close rules
|
||||
|
||||
Close a linked issue only if:
|
||||
|
||||
* exact issue-close capability is proven
|
||||
* linked issue was fetched live
|
||||
* issue resolution is justified by landed content and project policy
|
||||
* issue is still open at mutation time
|
||||
|
||||
If issue-close capability is missing, report the gap in the handoff.
|
||||
|
||||
## 15. Missing capability behavior
|
||||
|
||||
If any required mutation capability is missing:
|
||||
|
||||
* do not improvise with review/merge tools
|
||||
* do not ask the operator to bypass capability gates
|
||||
* produce a recovery handoff listing exact missing capabilities
|
||||
* include safe next action (profile switch, human close, or dedicated reconciler
|
||||
profile)
|
||||
|
||||
## 16. Mutation classification
|
||||
|
||||
Use precise mutation categories in the final report:
|
||||
|
||||
* File edits by reconciler: (expect `none`)
|
||||
* Worktree/index mutations:
|
||||
* Git ref mutations: (`git fetch` belongs here, not read-only diagnostics)
|
||||
* MCP/Gitea mutations:
|
||||
* Reconciliation mutations: (PR comment, issue comment, PR close, issue close)
|
||||
* External-state mutations:
|
||||
* Read-only diagnostics:
|
||||
|
||||
Do not use legacy `Workspace mutations`.
|
||||
|
||||
## 17. Identity privacy rule
|
||||
|
||||
Report identity as `username / profile` (#305).
|
||||
|
||||
Do not disclose personal email in final reports unless explicitly required.
|
||||
|
||||
## 18. Precise final report
|
||||
|
||||
Include:
|
||||
|
||||
* canonical workflow source/version/hash
|
||||
* authenticated identity/profile
|
||||
* repo/project
|
||||
* capability proof summary (separate lines for inspect, comment, PR close,
|
||||
issue close)
|
||||
* inventory pagination proof
|
||||
* selected PR(s) with already-landed proof
|
||||
* linked issue live status
|
||||
* mutations performed or blocked
|
||||
* missing capabilities
|
||||
* confirmation that no normal review, approval, request-changes, or merge was
|
||||
performed
|
||||
|
||||
## 19. Local artifact and report consistency rule
|
||||
|
||||
Do not create local walkthrough, notes, markdown, JSON, or report artifacts
|
||||
during reconciliation unless explicitly required.
|
||||
|
||||
If any file is edited, report under `File edits by reconciler`.
|
||||
|
||||
Default: no repo file edits.
|
||||
|
||||
## 20. Forbidden unsupported claims unless proven
|
||||
|
||||
Do not claim:
|
||||
|
||||
* `already-landed`
|
||||
* `PR closed`
|
||||
* `issue closed`
|
||||
* `pagination complete`
|
||||
* `inventory complete`
|
||||
* `all gates passed`
|
||||
* `no unsafe mutation`
|
||||
|
||||
unless the corresponding proof is included.
|
||||
|
||||
## 21. Proof wording enforcement
|
||||
|
||||
Forbidden unless supported by current-session evidence:
|
||||
|
||||
* pagination complete
|
||||
* final page
|
||||
* no next page
|
||||
* PR closed
|
||||
* issue closed
|
||||
* all gates passed
|
||||
|
||||
If proof comes from prior state, label as prior proof, not live proof.
|
||||
|
||||
## 22. Final self-check before output
|
||||
|
||||
Verify:
|
||||
|
||||
* no normal review/merge mutations occurred
|
||||
* `git fetch` is under Git ref mutations if it occurred
|
||||
* already-landed proof is present for each selected PR
|
||||
* handoff uses reconciliation schema, not author/reviewer merge schema
|
||||
* no contradiction between narrative report and controller handoff
|
||||
|
||||
## 23. Controller handoff schema
|
||||
|
||||
End every run with `Controller Handoff` per
|
||||
[`schemas/reconcile-landed-final-report.md`](../schemas/reconcile-landed-final-report.md).
|
||||
|
||||
## 24. Stop conditions summary
|
||||
|
||||
Stop immediately and produce a recovery handoff if:
|
||||
|
||||
* canonical workflow cannot be loaded
|
||||
* identity/profile/capability cannot be proven
|
||||
* runtime context is blocked
|
||||
* `infra_stop` appears
|
||||
* inventory pagination cannot be proven and best-effort is not allowed
|
||||
* already-landed proof cannot be completed
|
||||
* required close capability is missing and mutation was attempted
|
||||
* live PR/issue state contradicts proof
|
||||
* any report contradiction cannot be resolved
|
||||
|
||||
Do not improvise around the gates.
|
||||
File diff suppressed because it is too large
Load Diff
Reference in New Issue
Block a user