Files

T

sysadminandClaude Fable 5 45c5cac2bc Require and validate Controller Handoff sections in workflow final reports

- Upgrade SKILL.md §K compact format to the issue #182 canonical field set
  (Task/Repo/Role/Identity/Issue-PR/Branch-SHA/Files/Validation/Mutations/
  Current status/Blockers/Next/Safety) plus role-specific field lists for
  review/merge, author, and queue/inventory tasks.
- Point the review-pr, merge-pr, and start-issue template handoff lines at
  the exactly-titled Controller Handoff section with their role fields.
- Add review_proofs.assess_controller_handoff(): reports without the exact
  section are 'missing' (downgraded), present-but-partial are 'incomplete'
  with the absent fields listed, and role extras are enforced per role.
- Add TestControllerHandoff (8 tests) including a SKILL.md doc-contract
  test so the documented requirement cannot silently rot.

The handoff supplements the full report; full-report validation rules are
unchanged.

Closes #182

Co-Authored-By: Claude Fable 5 <[email protected]>

2026-07-05 15:36:57 -04:00

4.3 KiB

Raw Blame History

Template: review a PR

Copy, fill the <...> fields, and paste as the task prompt.

Task: review PR #<pr> for issue #<n>.

Repo name disambiguation (Gitea-Tools blind review hardening):
- "Gitea-Tools", "gitea tool", "MCP Gitea tool", "gitea MCP tool", "gitea-tools repo"
  → MUST resolve to `Scaled-Tech-Consulting/Gitea-Tools` (never treat as mcp-control-plane).
- "mcp-control-plane", "mcp control plane" → only `Scaled-Tech-Consulting/mcp-control-plane`.
- If user says "open PRs", "the queue", "MCP Gitea tooling" without explicit repo,
  or reference is ambiguous: check BOTH configured repos:
  `Scaled-Tech-Consulting/Gitea-Tools` and `Scaled-Tech-Consulting/mcp-control-plane`.
- In the final report, always state exactly which repo(s) were checked.
  If only one was checked: explicitly say "Only <repo> was checked. Other
  configured repos were not checked. This is not a complete queue inventory."
- A single-repo "no open PRs" result MUST NOT be reported as global "no open PRs"
  if the other configured repo was not inventoried.

Rules (llm-project-workflow):
- Review in a SEPARATE detached review worktree, never the author's folder.
- You must NOT be the PR author. If the authenticated user == PR author, stop.
  A different LLM-Agent-SHA does NOT make you a different actor — only a
  different authenticated Gitea user does (docs/llm-agent-sha.md).
- Do not merge if any check fails.

Steps:
1. Identity Checklist: Before claiming/working on review, verify and state:
   - Required identity/profile for this task: reviewer (allowed to review/approve/request_changes)
   - Current authenticated identity (from whoami): <username>
   - Target task role: reviewer identity (must NOT be the PR author)
   *If the current identity does not match the required role (or is the PR author), STOP. Relaunch/switch to the correct profile first.*
2. Verify your authenticated identity (whoami) and the active profile.
3. Fetch the PR facts: PR author, head SHA, state (must be open), base branch.
   Pin the head SHA in your notes; every later step validates THAT SHA.
4. If authenticated user == PR author → STOP (no self-review).
   Session-contamination claims must be evidence-backed (#173): if you
   cannot evidence whether this session authored/touched the PR branch,
   report contamination as UNKNOWN (not contaminated, not clean) and choose
   another PR or stop.
5. scripts/worktree-review <pr-head-branch>          # detached, branches/review-*
   cd branches/review-<pr-head-branch-slug>
6. Checkout proof (#173) — prove and state, before any diff review or
   validation:
   - pinned PR head SHA (from Gitea)
   - local checkout SHA (git rev-parse HEAD)
   - HEAD == pinned PR head SHA
   - diff base == the PR base branch
   If HEAD does not match the pinned head → STOP before review/merge.
7. Confirm the worktree is clean. Inspect the FULL diff; confirm scope matches
   issue #<n>; flag any unrelated files, secrets, or formatting churn. Check that the PR body correctly uses Gitea-closing keywords (`Closes #N` or `Fixes #N`) instead of non-closing ones (`Implements #N`, `Refs #N`).
8. Run the test suite; report the exact command and exact results — pass/fail
   plus passed/skipped/failed counts, any ignored paths and why they are safe
   to ignore, and whether the command differs from the repository's canonical
   validation command. Only claim a result after the output has been read.
9. Post the review verdict: approve only if scope is clean and checks pass;
   otherwise request changes with specifics. Never merge from this review step.
   Include a "Review Metadata" block (attribution only — docs/llm-agent-sha.md):

   Review Metadata:
   - LLM-Agent-SHA: llm-<12 lowercase hex, e.g. llm-41d0e7aa9f2c>
   - LLM-Role: reviewer
   - Authenticated-Gitea-User: <whoami result>
   - MCP-Profile: <profile name>
   - Eligibility: passed/failed

Handoff: end with a section titled exactly `Controller Handoff` per SKILL.md
§K (compact by default; long form if a merge happened or a gate blocked you),
including the review/merge role fields: Selected PR, Reviewer eligibility,
Pinned reviewed head, Review decision, Merge result, Linked issue status,
Cleanup status. If you could not merge, name the exact gate. Reports missing
the handoff are downgraded (review_proofs.assess_controller_handoff).

4.3 KiB Raw Blame History

Template: review a PR

4.3 KiB

Raw Blame History