Scaled-Tech-Consulting/Gitea-Tools
2
0
Fork 0
Code Issues 73 Pull Requests 9 Actions Packages Projects Releases Wiki Activity

Require controller handoff summaries in all LLM workflow final reports #182

New Issue
Closed
opened 2026-07-05 14:20:22 -05:00 by jcwalker3 · 5 comments
jcwalker3 commented 2026-07-05 14:20:22 -05:00
Owner
Copy Link
Copy Source

Problem:
Recent LLM runs are producing long final reports, but they often omit a compact controller handoff summary. This makes it harder for the next controller/operator to continue the queue without rereading the entire transcript.

Example:
A recent author run for Gitea-Tools issue #177 / PR #181 included useful details, but did not end with a clearly labeled controller handoff block. The report covered identity, role, queue state, selected issue, branch/SHA, files changed, validation, PR number, and follow-ups, but the next controller still has to extract the actionable state manually.

Required behavior:
Every LLM workflow final report must include a compact section titled exactly:

Controller Handoff

The handoff must be short, structured, and suitable for copy/paste into the next LLM/controller session.

Required fields:

  • Task completed
  • Repo
  • Identity/profile used
  • Role selected
  • Issue/PR worked
  • Branch
  • Head SHA
  • Base SHA, if known
  • Files changed
  • Validation commands and results
  • Mutations performed
  • Current issue/PR status
  • Blockers
  • Next recommended action
  • Safety notes

For review/merge workflows, also include:

  • selected PR
  • reviewer eligibility result
  • pinned reviewed head
  • review decision
  • merge result
  • linked issue status
  • cleanup status

For author workflows, also include:

  • selected issue
  • claim/comment status
  • PR number opened
  • confirmation no review/merge was attempted

For queue/inventory workflows, also include:

  • repositories checked
  • open PR counts per repo
  • selected PR or reason none selected
  • whether inventory was complete or scoped

Acceptance criteria:

  • skills/llm-project-workflow/SKILL.md requires a Controller Handoff section in every final report.
  • Relevant templates include the Controller Handoff section:
    • review PR template
    • start issue template
    • author PR creation template
    • queue inventory template, if present
  • Tests or proof helpers reject/downgrade final reports that omit the handoff.
  • The handoff must not replace the full report; it is a compact continuation summary at the end.
  • The final report must still include exact validation results and mutation confirmation.

Suggested canonical format:

Controller Handoff:

  • Task:
  • Repo: <org/repo>
  • Role: <author/reviewer/inventory>
  • Identity: <username/profile>
  • Issue/PR:
  • Branch/SHA: <branch + head SHA>
  • Files changed:
  • Validation:
  • Mutations:
  • Current status: <open/merged/closed/in-progress>
  • Blockers:
  • Next:
  • Safety: <no review/merge if author, no issue close, no unrelated mutations, etc.>

Related / prior art:

  • #101 (PR #102) introduced the Controller Handoff Summary requirement; #108 (PR #115) made the compact format the default. This issue extends that work: exact section title, role-specific field sets, template coverage (review/start-issue/author-PR/queue-inventory), and — new — proof-helper/test enforcement that downgrades reports missing the handoff.
  • Complements #179 (A-level reviewer proofs): the handoff is the continuation-facing summary; #179's proofs are the evidence body it summarizes.
Problem: Recent LLM runs are producing long final reports, but they often omit a compact controller handoff summary. This makes it harder for the next controller/operator to continue the queue without rereading the entire transcript. Example: A recent author run for Gitea-Tools issue #177 / PR #181 included useful details, but did not end with a clearly labeled controller handoff block. The report covered identity, role, queue state, selected issue, branch/SHA, files changed, validation, PR number, and follow-ups, but the next controller still has to extract the actionable state manually. Required behavior: Every LLM workflow final report must include a compact section titled exactly: Controller Handoff The handoff must be short, structured, and suitable for copy/paste into the next LLM/controller session. Required fields: * Task completed * Repo * Identity/profile used * Role selected * Issue/PR worked * Branch * Head SHA * Base SHA, if known * Files changed * Validation commands and results * Mutations performed * Current issue/PR status * Blockers * Next recommended action * Safety notes For review/merge workflows, also include: * selected PR * reviewer eligibility result * pinned reviewed head * review decision * merge result * linked issue status * cleanup status For author workflows, also include: * selected issue * claim/comment status * PR number opened * confirmation no review/merge was attempted For queue/inventory workflows, also include: * repositories checked * open PR counts per repo * selected PR or reason none selected * whether inventory was complete or scoped Acceptance criteria: * `skills/llm-project-workflow/SKILL.md` requires a Controller Handoff section in every final report. * Relevant templates include the Controller Handoff section: * review PR template * start issue template * author PR creation template * queue inventory template, if present * Tests or proof helpers reject/downgrade final reports that omit the handoff. * The handoff must not replace the full report; it is a compact continuation summary at the end. * The final report must still include exact validation results and mutation confirmation. Suggested canonical format: Controller Handoff: * Task: <what was completed> * Repo: <org/repo> * Role: <author/reviewer/inventory> * Identity: <username/profile> * Issue/PR: <numbers and titles> * Branch/SHA: <branch + head SHA> * Files changed: <short list> * Validation: <exact results> * Mutations: <what changed remotely> * Current status: <open/merged/closed/in-progress> * Blockers: <none or specific> * Next: <next recommended action> * Safety: <no review/merge if author, no issue close, no unrelated mutations, etc.> Related / prior art: * #101 (PR #102) introduced the Controller Handoff Summary requirement; #108 (PR #115) made the compact format the default. This issue extends that work: exact section title, role-specific field sets, template coverage (review/start-issue/author-PR/queue-inventory), and — new — proof-helper/test enforcement that downgrades reports missing the handoff. * Complements #179 (A-level reviewer proofs): the handoff is the continuation-facing summary; #179's proofs are the evidence body it summarizes.
sysadmin commented 2026-07-05 14:21:55 -05:00
Owner
Copy Link
Copy Source

PR #79 Reviewer Run Handoff Evidence

A reviewer run successfully reviewed and merged mcp-control-plane PR #79 for Issue #78.

Observed Positive Behavior:

  • Authenticated as sysadmin / prgs-reviewer.
  • Checked both configured repositories:
    • Scaled-Tech-Consulting/Gitea-Tools: PR #180 and PR #181 open.
    • Scaled-Tech-Consulting/mcp-control-plane: PR #79 open and selected.
  • Selected one eligible PR.
  • Pinned and checked out head e3b1b66a764a4d3a68565482e9268617e20b682e.
  • Verified local HEAD matched the pinned SHA.
  • Ran validation:
    • ./venv/bin/pytest tests/test_controller_capabilities.py tests/test_controller_reports.py tests/test_issue_escalation.py → 31/31 passed
    • ./venv/bin/pytest → 431 passed, 0 failures, 13 skipped
    • python3 -m py_compile → passed
    • git diff --check prgs/master...HEAD → passed
  • Approved and merged only PR #79.
  • Left Gitea-Tools PR #180 and #181 open for later review.
  • Issue #78 closed after merge.

Remaining Gap:

  • Missing Controller Handoff block: The final report was structured but did not include a compact section titled exactly Controller Handoff at the end, confirming the need for templates and tests to require and enforce this block.
### PR #79 Reviewer Run Handoff Evidence A reviewer run successfully reviewed and merged `mcp-control-plane` [PR #79](https://gitea.prgs.cc/Scaled-Tech-Consulting/mcp-control-plane/pulls/79) for Issue #78. #### Observed Positive Behavior: * Authenticated as `sysadmin / prgs-reviewer`. * Checked both configured repositories: * `Scaled-Tech-Consulting/Gitea-Tools`: PR #180 and PR #181 open. * `Scaled-Tech-Consulting/mcp-control-plane`: PR #79 open and selected. * Selected one eligible PR. * Pinned and checked out head `e3b1b66a764a4d3a68565482e9268617e20b682e`. * Verified local `HEAD` matched the pinned SHA. * Ran validation: * `./venv/bin/pytest tests/test_controller_capabilities.py tests/test_controller_reports.py tests/test_issue_escalation.py` → `31/31 passed` * `./venv/bin/pytest` → `431 passed, 0 failures, 13 skipped` * `python3 -m py_compile` → passed * `git diff --check prgs/master...HEAD` → passed * Approved and merged only PR #79. * Left Gitea-Tools PR #180 and #181 open for later review. * Issue #78 closed after merge. #### Remaining Gap: * **Missing Controller Handoff block**: The final report was structured but did not include a compact section titled exactly `Controller Handoff` at the end, confirming the need for templates and tests to require and enforce this block.
jcwalker3 commented 2026-07-05 14:25:27 -05:00
Author
Owner
Copy Link
Copy Source

Claimed (comment-claim only). Branch: feat/issue-182-controller-handoff-enforcement.

Note on claim mechanics: gitea_resolve_task_capability(task=mark_issue) fails closed with "Unknown task/action: 'mark_issue'" — per exact-mutation-capability discipline (mcp-control-plane #77, Gitea-Tools #183) I am not calling gitea_mark_issue while the resolver cannot map it, so no status:in-progress label will be set by this run. This comment is the claim record. The unmapped claim task is live evidence for #183's exact issue-claim capability requirement.

Plan: implement #182 as scoped — require exactly-titled Controller Handoff section in llm-project-workflow SKILL.md final reports; add the section to review-PR / start-issue / author-PR / queue-inventory templates as present; add proof-helper validation + tests that downgrade reports missing the handoff; keep full report + exact validation requirements intact.

Scope note: #183 overlaps this issue on the handoff requirement; #183's additional items (claim capability, sweep evidence, head SHA fields) are NOT in this unit's scope — no consolidation performed under this claim.

Claimed (comment-claim only). Branch: `feat/issue-182-controller-handoff-enforcement`. Note on claim mechanics: `gitea_resolve_task_capability(task=mark_issue)` fails closed with "Unknown task/action: 'mark_issue'" — per exact-mutation-capability discipline (mcp-control-plane #77, Gitea-Tools #183) I am not calling `gitea_mark_issue` while the resolver cannot map it, so no `status:in-progress` label will be set by this run. This comment is the claim record. The unmapped claim task is live evidence for #183's exact issue-claim capability requirement. Plan: implement #182 as scoped — require exactly-titled `Controller Handoff` section in llm-project-workflow SKILL.md final reports; add the section to review-PR / start-issue / author-PR / queue-inventory templates as present; add proof-helper validation + tests that downgrade reports missing the handoff; keep full report + exact validation requirements intact. Scope note: #183 overlaps this issue on the handoff requirement; #183's additional items (claim capability, sweep evidence, head SHA fields) are NOT in this unit's scope — no consolidation performed under this claim.
jcwalker3 commented 2026-07-05 14:30:48 -05:00
Author
Owner
Copy Link
Copy Source

PR #180 Reviewer Run Evidence

A reviewer run was asked to continue working the issue/PR queue without a specific issue selected. It authenticated as sysadmin / prgs-reviewer, checked both configured repos, and safely stopped without mutation.

Observed State:

  • Gitea-Tools PR #180 was initially open but merged during the run:
    • merged at 2026-07-05T14:26:32-05:00
    • merge commit 340b585bfdfdc267c4fc1aad26a38b9727091b6e
    • linked issue #178 closed
  • Gitea-Tools PR #181 remains open:
    • branch feat/issue-177-branch-drift-proofs
    • head 941ada38c2b95067294c18eb86f18b4437e6c822
    • base master
    • mergeable according to Gitea
    • stale against live prgs/master
    • prgs/master = 340b585bfdfdc267c4fc1aad26a38b9727091b6e
    • PR merge-base = 64dc334a92685b7b6a1fdb7ffe363f02a69f5dbd
    • git merge-base --is-ancestor prgs/master prgs/feat/issue-177-branch-drift-proofs exited 1
  • mcp-control-plane had no open PRs.
  • No review, merge, issue, branch, push, or comment mutation was performed.

Positive Behavior:

  • reviewer profile did not pivot into author work
  • stale PR was not reviewed or merged
  • both configured repos were inventoried
  • no unsafe mutation occurred

Observed Gap:

The final report did not include a compact Controller Handoff block, and stale-PR next steps were not packaged into a copy/paste-ready handoff for the next author/controller.

Required Behavior:

  1. Every queue reconciliation report must include a Controller Handoff section.
  2. When the only remaining open PR is stale, the handoff must explicitly say:
    • selected PR: none
    • stale PR number
    • stale branch
    • PR head SHA
    • current base SHA
    • merge-base SHA
    • exact stale check command/result
    • required next action: author must rebase/update branch before reviewer continues
  3. Reviewer profile must not implement the rebase/update.
  4. The workflow must distinguish:
    • no open PRs
    • open PRs exist but are stale
    • open PRs exist but are ineligible
    • reviewer queue reconciliation only
  5. Add tests/harness assertions:
    • stale PR prevents review/merge
    • stale PR report includes exact base/head/merge-base evidence
    • reviewer queue report without Controller Handoff is downgraded
    • reviewer profile does not pivot into author rebase work
    • handoff includes next author action

Acceptance Criteria:

A reviewer queue reconciliation earns an A only when it inventories all configured repos, categorizes stale/ineligible PRs correctly, performs no unsafe mutations, and ends with a compact Controller Handoff for the next operator.

### PR #180 Reviewer Run Evidence A reviewer run was asked to continue working the issue/PR queue without a specific issue selected. It authenticated as `sysadmin / prgs-reviewer`, checked both configured repos, and safely stopped without mutation. #### Observed State: * `Gitea-Tools` PR #180 was initially open but merged during the run: * merged at `2026-07-05T14:26:32-05:00` * merge commit `340b585bfdfdc267c4fc1aad26a38b9727091b6e` * linked issue #178 closed * `Gitea-Tools` PR #181 remains open: * branch `feat/issue-177-branch-drift-proofs` * head `941ada38c2b95067294c18eb86f18b4437e6c822` * base `master` * mergeable according to Gitea * stale against live `prgs/master` * `prgs/master` = `340b585bfdfdc267c4fc1aad26a38b9727091b6e` * PR merge-base = `64dc334a92685b7b6a1fdb7ffe363f02a69f5dbd` * `git merge-base --is-ancestor prgs/master prgs/feat/issue-177-branch-drift-proofs` exited `1` * `mcp-control-plane` had no open PRs. * No review, merge, issue, branch, push, or comment mutation was performed. #### Positive Behavior: * reviewer profile did not pivot into author work * stale PR was not reviewed or merged * both configured repos were inventoried * no unsafe mutation occurred #### Observed Gap: The final report did not include a compact `Controller Handoff` block, and stale-PR next steps were not packaged into a copy/paste-ready handoff for the next author/controller. #### Required Behavior: 1. Every queue reconciliation report must include a `Controller Handoff` section. 2. When the only remaining open PR is stale, the handoff must explicitly say: * selected PR: none * stale PR number * stale branch * PR head SHA * current base SHA * merge-base SHA * exact stale check command/result * required next action: author must rebase/update branch before reviewer continues 3. Reviewer profile must not implement the rebase/update. 4. The workflow must distinguish: * no open PRs * open PRs exist but are stale * open PRs exist but are ineligible * reviewer queue reconciliation only 5. Add tests/harness assertions: * stale PR prevents review/merge * stale PR report includes exact base/head/merge-base evidence * reviewer queue report without Controller Handoff is downgraded * reviewer profile does not pivot into author rebase work * handoff includes next author action #### Acceptance Criteria: A reviewer queue reconciliation earns an A only when it inventories all configured repos, categorizes stale/ineligible PRs correctly, performs no unsafe mutations, and ends with a compact Controller Handoff for the next operator.
jcwalker3 commented 2026-07-05 14:33:36 -05:00
Author
Owner
Copy Link
Copy Source

PR #186 opened for this issue — head bd6cbe287b3e86f22547bf1770a272a509c63f7a from feat/issue-182-controller-handoff-enforcement, base master @ 64dc334a.

Scope delivered: SKILL.md §K canonical compact format + role extras, three template handoff lines updated, assess_controller_handoff() proof helper, 8 tests including SKILL.md doc-contract. Validation: 43/43 targeted, full suite 683 passed / 6 skipped (junitxml: 689 tests, 0 failures, 0 errors, 6 skipped).

Review needed — PR is open. Author stops here; no review/merge attempted.

PR #186 opened for this issue — head `bd6cbe287b3e86f22547bf1770a272a509c63f7a` from `feat/issue-182-controller-handoff-enforcement`, base `master` @ `64dc334a`. Scope delivered: SKILL.md §K canonical compact format + role extras, three template handoff lines updated, `assess_controller_handoff()` proof helper, 8 tests including SKILL.md doc-contract. Validation: 43/43 targeted, full suite 683 passed / 6 skipped (junitxml: 689 tests, 0 failures, 0 errors, 6 skipped). Review needed — PR is open. Author stops here; no review/merge attempted.
jcwalker3 commented 2026-07-05 14:38:22 -05:00
Author
Owner
Copy Link
Copy Source

PR #186 rebased onto current master and force-pushed (with lease): bd6cbe28 → 45c5cac2bc49dd112766ea218b18a71e9c5f8e99, base now master @ 601c608c (post PR #180/#185 merges). PR is mergeable: true again.

Conflict was one hunk: the tail of tests/test_review_proofs.py — PR #185's new tests (repo disambiguation, stdout isolation) vs this PR's TestControllerHandoff. Resolution kept both blocks; no content from either side dropped.

Revalidation at 45c5cac2:

  • targeted pytest tests/test_review_proofs.py -q → 50 passed (43 + 7 from #185 in the same file)
  • full pytest tests/ --ignore=branches -q → 690 passed, 6 skipped
  • git diff --check prgs/master...HEAD → clean
  • python3 -m py_compile $(git ls-files '*.py') → OK
  • secret sweep (grep -iE 'token |Bearer |password|secret_|api_key|ghp_|keychain' over rebased diff) → clean

Review needed — PR is open. No review/merge attempted.

PR #186 rebased onto current master and force-pushed (with lease): `bd6cbe28` → **`45c5cac2bc49dd112766ea218b18a71e9c5f8e99`**, base now `master` @ `601c608c` (post PR #180/#185 merges). PR is `mergeable: true` again. Conflict was one hunk: the tail of `tests/test_review_proofs.py` — PR #185's new tests (repo disambiguation, stdout isolation) vs this PR's `TestControllerHandoff`. Resolution kept both blocks; no content from either side dropped. Revalidation at `45c5cac2`: - targeted `pytest tests/test_review_proofs.py -q` → 50 passed (43 + 7 from #185 in the same file) - full `pytest tests/ --ignore=branches -q` → 690 passed, 6 skipped - `git diff --check prgs/master...HEAD` → clean - `python3 -m py_compile $(git ls-files '*.py')` → OK - secret sweep (`grep -iE 'token |Bearer |password|secret_|api_key|ghp_|keychain'` over rebased diff) → clean Review needed — PR is open. No review/merge attempted.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
allocator
Controller-owned work allocator
 anti-stomp
Prevent concurrent LLM session stomping
 architecture
Architecture / structural design
 bug
chore
codex
OpenAI Codex client / workflow session surface
 concurrency
Concurrent session safety
 contamination
Workflow or session contamination incident
 control-plane
MCP control-plane coordination and allocation authority
 dashboard
MCP operational dashboard/queue view
 database
Internal coordination storage (SQLite/Postgres)
 design
Design / investigation, no implementation
 documentation
Docs / runbooks
 enhancement
New feature or improvement
 gitea
Gitea MCP workflow
 glitchtip
GlitchTip integration
 important
incident
Operational or process incident requiring durable audit trail
 incident-bridge
Sentry-to-Gitea incident bridging
 integration
Integration testing
 jenkins
Jenkins integration
 labels
Label taxonomy management
 leases
Lease adopt/release/expire lifecycle
 mcp
MCP server / tooling
 mcp-health
MCP namespace and runtime health
 mcp-menu
MCP menu surface
 multi-project
Work spanning multiple monitoring projects or Gitea repos
 mutating
Mutating action; requires gating
 nice-to-have
observability
Observability, metrics, traces, error reporting
 portability
Cross-platform / portability
 preflight
Shared preflight gates before mutation
 protected-branch
Protected branch / stable-branch policy concern
 queue
Work queue visibility and allocation
 read-only
Read-only, no mutation
 reconnect
MCP client reconnect/reload recovery path
 recovery
Recovery paths for stale/foreign leases
 refactor
Code refactor / restructure
 release
Release / versioning
 reliability
Reliability / failure handling
 resumable-review
Persist and resume prepared review verdicts across sessions
 reviewer
Reviewer workflow tooling
 roadmap
Roadmap / umbrella issue
 safety
Safety rails and fail-closed mutation guards
 security
Security / trust boundary
 self-hosted
Self-hosted infrastructure integration
 sentry
Sentry error monitoring integration
 stale-runtime
Stale backend daemon / runtime-vs-master parity failures
 status:blocked
Issue is blocked
 status:in-progress
Issue is being worked on
 status:pr-open
Issue has an open pull request
 status:ready
Issue is ready for work
 terminal-lock
Terminal review lock (#332) path
 testing
Tests / test coverage
 tracker
Issue tracker hygiene / meta
 type:bug
Bug or defect
 type:feature
Feature or enhancement
 type:feature
Feature or enhancement
 type:guardrail
Safety gate or guardrail
 visibility
Workflow state visibility for LLMs/operators
 workflow
Cross-tool workflow
 workflow-hardening
LLM workflow coordination hardening
 workflow-hardening
LLM workflow coordination hardening
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
jcwalker3 sysadmin
No Assignees
2 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

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