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>
This commit is contained in:
2026-07-02 18:17:03 -04:00
parent cdc32669c7
commit f09791e049
4 changed files with 182 additions and 4 deletions
+23
View File
@@ -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,