docs: require Controller Handoff Summary + codify LLM workflow rules (#101)

- SKILL.md: new §K Controller Handoff Summary (required every task type) with the exact format and a worked blocked-handoff example; issue-first rule extended (discussion/RFC issues, unclear-tracker-home stop rule, no new repo/tracker without owner approval); merge workflow now names identity+author verification, profile gates, independent validation, and pinned head SHA / expected changed-file merges; tagging rules extended (no tag ops unless instructed, tag only the verified final master merge commit, always report tag target). - llm-workflow-runbooks.md: Controller Handoff Summary section pointing at SKILL §K, incl. discussion/RFC rule (e.g. #100 stays a discussion issue). - templates/start-issue.md + review-pr.md: handoff lines now reference the required summary format and the exact-gate reporting rule. Docs only; no code behavior changed. No tags touched; #100 not modified. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
2026-07-02 18:17:03 -04:00
parent cdc32669c7
commit f09791e049
4 changed files with 182 additions and 4 deletions
@@ -337,6 +337,29 @@ touching anything.
  files, detected secret, or any production/deploy behavior — **stop, report the
  blocker, and take no mutating action.** Fail closed; never work around a gate.

+## Controller Handoff Summary (required, every task)
+
+Every task — implementation, review, merge, triage, documentation,
+discussion-only, or blocked planning — **must end with a
+`Controller Handoff Summary`** so a controller LLM can pick up the state
+without rereading the conversation. The canonical format and rules live in the
+portable skill:
+[`../skills/llm-project-workflow/SKILL.md`](../skills/llm-project-workflow/SKILL.md) §K.
+
+Sections (in order): Work performed · Current state (repo, branch/master
+commit, issue #s, PR #s, complete/blocked/ready-for-review/discussion-only) ·
+Files changed · Validation · Issues encountered · Review needed? (one of the
+five fixed answers) · Next recommended action · Safety confirmations
+(no self-review; no self-merge; no release/tag changes unless requested; no
+secrets; no production access unless authorized).
+
+Hard rules: never omit it; never bury blockers earlier only; an opened PR
+means "Review needed — PR is open"; a blocked merge names the exact gate;
+discussion-only comments need owner/design feedback, not code review; any
+touched release state names the exact tag/commit and why. Design debates
+belong in **discussion/RFC issues** (e.g. #100 `profiles.json v2`) — comment
+on the issue, create no branches/PRs, and end the comment with this summary.
+
 ## Fail-closed behavior

 Before any mutating action the workflow verifies identity, active profile,
@@ -41,6 +41,18 @@ editing, deleting, or `chmod`-ing files; docs; scripts; commits; pushes; and PRs
 Reading the repo, running read-only status/`git log`, and creating/claiming the
 issue itself are allowed from the orchestration checkout without a prior issue.

+Additional issue-first rules:
+
+- Do not implement code without an issue unless explicitly authorized.
+- **Design-only work uses a discussion/RFC issue** — create one or comment on
+  the existing one. Design debates belong on the issue, where other LLMs
+  comment directly. Discussion-only tasks must **not** create branches or PRs;
+  their comments should include recommendations, risks, open questions, and a
+  Controller Handoff Summary (§K).
+- **If the repo/tracker home for the work is unclear, stop and ask for an
+  owner decision.** Do not create a new repository or a new tracker unless
+  explicitly approved by the owner.
+
 ## B. Isolated worktree rule

 **Never implement or review in the main checkout.** The main checkout is for
@@ -162,7 +174,12 @@ Worktree folder = branch with `/` replaced by `-`

 ## G. Merge / cleanup workflow

-Only an eligible (non-author) reviewer merges. After a real merge:
+Only an eligible (non-author) reviewer merges. Before merging: always verify
+the authenticated identity **and** the PR author; respect runtime profile
+gates; run independent validation (do not trust the author's reported
+results); and merge with a **pinned head SHA** and, where supported, the
+**expected changed-file set**, so a moved head or widened diff refuses the
+merge. After a real merge:

 1. Confirm remote `master` actually contains the merge commit (A PR is not done just because `master` moved. A PR is done only when: Gitea reports the PR merged or reconciliation documents equivalent content on `master`; remote `master` contains the expected content; linked issues are closed; `status:in-progress` is removed).
 2. Close/release the issue.
@@ -230,6 +247,132 @@ Ready-to-copy templates live in [`templates/`](templates/):
 - [`worktree-cleanup.md`](templates/worktree-cleanup.md) — clean up after merge.
 - [`release-tag.md`](templates/release-tag.md) — create a release tag.

+## K. Controller Handoff Summary (required, every task)
+
+Every LLM task **must end with a `Controller Handoff Summary`** — whether the
+task was implementation, review, merge, issue triage, documentation,
+discussion-only, or blocked planning. It lets a controller LLM understand the
+current state immediately, without rereading the conversation.
+
+Rules:
+
+- Never omit the summary.
+- Never bury blockers in earlier text only — they must appear here.
+- If you opened a PR, state clearly that review is needed.
+- If you reviewed but could not merge, name the exact gate that blocked it.
+- If you only commented on a discussion issue, say no code review is needed
+  but owner/design feedback may be needed.
+- If release state was touched, state exactly which tag/commit changed and why.
+- If blocked (permissions, missing repo, missing second reviewer identity,
+  stale dependency, unclear tracker home): stop and report clearly; **never
+  bypass classifiers, profile gates, missing permissions, or live-consent
+  requirements**; give the owner concrete options.
+
+Required format:
+
+```md
+## Controller Handoff Summary
+
+### Work performed
+
+Briefly state what was done.
+
+### Current state
+
+Include:
+- current repo
+- current branch or master commit
+- issue number(s)
+- PR number(s), if any
+- whether work is complete, blocked, ready for review, or discussion-only
+
+### Files changed
+
+List files changed, or say `None`.
+
+### Validation
+
+List commands run and results, or say `Not applicable — discussion only`.
+
+### Issues encountered
+
+List errors, confusing state, permission/profile problems, stale branches,
+failing tests, missing labels, or blocked decisions.
+
+### Review needed?
+
+Say one of:
+- `No review needed — discussion/comment only`
+- `Review needed — PR is open`
+- `Independent non-author review needed`
+- `Owner decision needed`
+- `Blocked`
+
+### Next recommended action
+
+State exactly what should happen next.
+
+### Safety confirmations
+
+Confirm:
+- no self-review
+- no self-merge
+- no release/tag changes unless explicitly requested
+- no secrets committed
+- no production access used unless explicitly authorized
+```
+
+### Example blocked handoff
+
+```md
+## Example blocked handoff
+
+### Work performed
+
+Audited phase-2 MCP Control Plane planning. Found target repo
+`mcp-control-plane` does not exist. Prepared issue pack but did not file it.
+
+### Current state
+
+- Repo: `Scaled-Tech-Consulting/Gitea-Tools`, unmodified
+- Target repo: `mcp-control-plane`, missing
+- Issues: none open in Gitea-Tools
+- PRs: none open
+- Status: blocked pending owner decision
+
+### Files changed
+
+None.
+
+### Validation
+
+Tracker/repo audit only. No code validation required.
+
+### Issues encountered
+
+Repo creation was denied by permission/classifier because it would be scope
+escalation without live consent.
+
+### Review needed?
+
+Owner decision needed.
+
+### Next recommended action
+
+Owner must choose:
+1. create `Scaled-Tech-Consulting/mcp-control-plane`
+2. authorize repo creation while present
+3. file phase-2 issues in Gitea-Tools instead
+
+### Safety confirmations
+
+- no self-review
+- no self-merge
+- no release/tag changes
+- no secrets committed
+- no production access used
+```
+
 ## Adapting to a project

 Replace these project-specific names when copying the skill elsewhere:
@@ -242,7 +385,7 @@ Replace these project-specific names when copying the skill elsewhere:
 | `branches/` | Ignored worktree directory | `branches/` |
 | helper scripts | Worktree helpers | `scripts/worktree-start` / `-review` / `-clean` |

-The rules in §A–§I are project-agnostic and should not change.
+The rules in §A–§K are project-agnostic and should not change.

 ## Versioning And Tagging

@@ -263,6 +406,14 @@ Tags must:
 **Never tag** feature branches, dirty worktrees, unreviewed or self-authored
 work, or commits not present on remote `master`.

+Additional tag rules:
+
+- Do **not** create, move, delete, or push tags unless explicitly instructed.
+- Tag only **after** the intended PR is merged, and tag only the **verified
+  final master merge commit** (never the PR branch head unless the merge
+  commit is exactly that commit).
+- Always **report the tag target commit** in the final report / handoff.
+
 Release process (see [`templates/release-tag.md`](templates/release-tag.md)):

 1. `git fetch <remote> --prune`.
@@ -32,5 +32,7 @@ Steps:
   - MCP-Profile: <profile name>
   - Eligibility: passed/failed

-Handoff: reviewer identity, PR author, scope verdict, checks + results, decision.
+Handoff: reviewer identity, PR author, scope verdict, checks + results, decision —
+formatted as the Controller Handoff Summary (SKILL.md §K); if you could not
+merge, name the exact gate that blocked it.
 ```
@@ -36,5 +36,7 @@ Steps:
   - Self-review allowed: no
 8. Stop before review/merge — you are the author.

-Handoff: issue #, branch, worktree path, files changed, checks + results, PR URL.
+Handoff: issue #, branch, worktree path, files changed, checks + results, PR URL —
+formatted as the Controller Handoff Summary (SKILL.md §K); end with
+"Review needed — PR is open".
 ```