- 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]>
Adds author_proofs.py, the author-side counterpart of review_proofs.py
(#173), turning the branch-drift incident from PR #176 into fail-closed
gates:
- verify_branch_for_commit: the current branch must equal the intended
feature branch and may never be a protected branch (master, main,
develop, development, dev); missing state fails closed.
- detect_branch_drift: any branch or HEAD change between validation time
and commit time — including an external branch switch in a shared
worktree, which is treated as an expected event to detect — blocks the
commit until reconciled.
- verify_push_target: a push requires the local branch, remote target
branch, and intended issue branch to all match, none protected.
- assess_protected_branch_commit: an accidental protected-branch commit
must never be pushed, requires repair, and the repair must be reported;
pushing the accident or silently continuing is a violation.
- build_commit_push_report: final-report block carrying the branch proof
before commit and before push; any failed proof, drift, or violation
makes the status blocked.
tests/test_author_proofs.py (27 tests) covers the issue's harness
assertions: commit on master blocked; drift between validation and commit
blocked; push target mismatch blocked; shared-worktree branch switch
detected; repair path cannot silently continue without reporting.
SKILL.md section E and templates/start-issue.md now require recording the
validation-time branch/HEAD, the branch proof before commit, the branch
proof before push, and non-silent accident repair. No review/merge/
permission gate is weakened.
Closes#177
Co-Authored-By: Claude Fable 5 <[email protected]>
Make the nine-line compact Controller Handoff the default end-of-task
format; reserve the long Controller Handoff Summary for high-risk/complex
tasks (merge/tag/release, failed validation, blocked gates, secrets/prod,
complicated owner decisions, cross-repo state, or explicit owner request).
Compact form is for controller-LLM readability, safety confirmations are
never omitted, and PR bodies still carry full review detail.
Updates SKILL.md §K, llm-workflow-runbooks.md, and the start-issue /
review-pr templates. Documentation only.
Refs #101. Closes#108.
Co-Authored-By: Claude Fable 5 <[email protected]>
Extract the project's operating rules into a reusable, project-agnostic skill
so any repo can adopt the same safe LLM workflow.
- skills/llm-project-workflow/SKILL.md: issue-first; isolated branch worktrees
(main checkout = orchestration only); distinct author/reviewer identities and
profile safety (secrets by reference only; stop if authenticated user == PR
author); branch naming; start/review/merge/cleanup workflows; fail-closed
cases; recovery patterns; and an "Adapting to a project" table for the
forge-specific names.
- templates/: copy/paste prompts for start-issue, review-pr, merge-pr,
recover-bad-state, worktree-cleanup.
- Link the skill from README.md and docs/llm-workflow-runbooks.md (the runbook
is framed as the Gitea-specific application of the portable skill).
Docs-only; no code, no secrets, safe placeholder examples only. No change to
MCP runtime, Gitea API, credential storage, or worktree helpers.
Checks: full suite 287 passed / 0 failures; git diff --check clean; secret scan
of skills/ clean.
Closes#46. Refs #38, #39.
Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
sysadmin
