Merge pull request 'Add fail-closed branch-identity proofs for author commit/push workflow (Issue #177)' (#181) from feat/issue-177-branch-drift-proofs into master

skills/llm-project-workflow/SKILL.md

@@ -150,12 +150,33 @@ Worktree folder = branch with `/` replaced by `-`
 6. Implement the narrow scope only — no unrelated refactors or formatting churn.
 7. Add/update focused tests when behavior changes.
 8. Run the checks (tests, compile/lint, `git diff --check`, secret scan).
-9. Commit with an issue-linked message.
-10. Push the branch.
-11. Open a PR to `master`.
-12. **If you are the author, stop before review/merge.**
-13. **Normal issue work must not directly push to `master`.** PR content should be merged through the forge PR merge mechanism.
-14. Direct push to `master` is allowed only as a documented recovery exception. If used, the final report must include:
+   Record the branch name and `HEAD` SHA at validation time — the drift
+   check in step 9 compares against exactly this state.
+9. **Branch proof before commit (#177):** prove and state, immediately
+   before staging/committing (`author_proofs.verify_branch_for_commit`,
+   `author_proofs.detect_branch_drift`):
+   - current branch (`git branch --show-current`) equals the intended
+     feature branch from the issue claim
+   - current branch is not `master`, `main`, `develop`, `development`, or
+     `dev`
+   - branch and `HEAD` have not changed since validation (step 8) — in a
+     shared checkout another session may switch branches mid-session;
+     treat that as expected and **stop before committing** when detected
+   If any check fails, stop and reconcile; do not commit.
+10. Commit with an issue-linked message.
+11. **Branch proof before push (#177):** prove that the local branch, the
+    push target branch, and the intended issue branch all match, and that
+    none of them is a protected branch
+    (`author_proofs.verify_push_target`). If a commit accidentally landed
+    on a protected branch, do **not** push: report the accident and the
+    exact repair steps (`author_proofs.assess_protected_branch_commit`) —
+    never silently continue after a repair.
+12. Push the branch.
+13. Open a PR to `master`. The final report must include the branch proofs
+    from steps 9 and 11 (`author_proofs.build_commit_push_report`).
+14. **If you are the author, stop before review/merge.**
+15. **Normal issue work must not directly push to `master`.** PR content should be merged through the forge PR merge mechanism.
+16. Direct push to `master` is allowed only as a documented recovery exception. If used, the final report must include:
     - why the PR merge path could not be used
     - exact commits pushed
     - PR metadata state

skills/llm-project-workflow/templates/start-issue.md

@@ -26,8 +26,19 @@ Steps:
    cd branches/<type>-issue-<n>-<slug>
 6. Implement the narrow scope only; add/update focused tests if behavior changes.
 7. Checks: run the test suite, compile/lint changed files, git diff --check,
-   and scan the diff for secrets.
-8. Commit (issue-linked message), push the branch, open a PR to master.
+   and scan the diff for secrets. Record the branch name and HEAD SHA at
+   validation time.
+8. Branch proof before commit (#177) — prove and state:
+   - git branch --show-current == the intended issue branch from step 5
+   - the branch is NOT master/main/develop/development/dev
+   - branch and HEAD unchanged since step 7 (another session can switch a
+     shared checkout mid-session; if drift is detected, STOP and reconcile
+     before committing)
+   If a commit accidentally lands on a protected branch: do NOT push;
+   report the accident and the exact repair steps — never silently continue.
+9. Commit (issue-linked message). Branch proof before push (#177): local
+   branch == push target branch == intended issue branch, none protected.
+   Then push the branch and open a PR to master.
    *The PR body MUST use closing keywords like `Closes #N` or `Fixes #N` to close the issue; do NOT use `Implements #N` or `Refs #N` for closing, as Gitea will not auto-close it.*
    Include an "LLM Handoff Metadata" block in the PR body (attribution only;
    never an eligibility input — docs/llm-agent-sha.md):
@@ -40,7 +51,7 @@ Steps:
    - Branch: <branch>
    - Worktree: <worktree path>
    - Self-review allowed: no
-9. Stop before review/merge — you are the author.
+10. Stop before review/merge — you are the author.
 
 Handoff: end with a section titled exactly `Controller Handoff` per SKILL.md
 §K (compact; long form only on the high-risk triggers), including the author