feat: surface explicit adoption proof in gitea_lock_issue response (Closes #477)

When gitea_lock_issue adopts an existing own branch, the live tool
response now carries explicit, citable adoption-proof fields so #473-style
recovery sessions can quote the lock output directly instead of inferring
adoption from separate offline checks.

- issue_lock_adoption.py: add DECISION_LABELS + decision_label()/
  safe_next_action() helpers; extend build_adoption_proof() with
  adoption_decision, adopted, adopted_branch, adopted_branch_head,
  matcher_summary (boundary-safe reason), competing_branch_check, and
  safe_next_action for all outcomes; add build_non_adoption_lock_proof()
  for adoption-free NO_MATCH metadata.
- gitea_mcp_server.py: attach adoption-free adoption_check block to normal
  (non-adopt) lock responses so they cannot be misread as claiming adoption.
- docs/llm-workflow-runbooks.md: document the adoption/adoption_check
  response blocks and instruct recovery reports to cite them directly.
- tests: explicit-field proof for ADOPT/BLOCK_COMPETING/NO_MATCH,
  substring-collision boundary safety (issue-42 vs issue-420), non-adoption
  proof, and MCP-level live-response assertions.

BLOCK_COMPETING lock attempts still fail closed (raise); no raw API
fallback, branch deletion, force-push, or manual lock seeding introduced.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>

tests/test_issue_lock_adoption.py

@@ -11,6 +11,7 @@ from issue_lock_adoption import (  # noqa: E402
     NO_MATCH,
     assess_own_branch_adoption,
     build_adoption_proof,
+    build_non_adoption_lock_proof,
 )
 
 REQ = "feat/issue-420-server-code-parity"
@@ -134,5 +135,93 @@ class TestBuildAdoptionProof(unittest.TestCase):
         self.assertTrue(proof["no_competing_live_lock_proof"])
 
 
+class TestExplicitAdoptionProofFields(unittest.TestCase):
+    """#477: explicit, citable adoption-proof fields for all outcomes."""
+
+    def _proof(self, assessment, branch):
+        return build_adoption_proof(
+            issue_number=420,
+            branch_name=branch,
+            assessment=assessment,
+            open_pr_checked=True,
+            competing_lock_checked=True,
+            lock_file_path="/tmp/example-lock.json",
+            lock_file_status="written",
+        )
+
+    def test_adopt_proof_exposes_explicit_fields(self):
+        assessment = assess_own_branch_adoption(
+            issue_number=420,
+            requested_branch=REQ,
+            existing_branches=[{"name": REQ, "commit_sha": "934688a"}],
+        )
+        proof = self._proof(assessment, REQ)
+        self.assertEqual(proof["adoption_decision"], "ADOPT")
+        self.assertTrue(proof["adopted"])
+        self.assertEqual(proof["adopted_branch"], REQ)
+        self.assertEqual(proof["adopted_branch_head"], "934688a")
+        self.assertEqual(proof["competing_branch_check"]["result"], "clear")
+        self.assertEqual(proof["competing_branch_check"]["competing_branches"], [])
+        self.assertIn("gitea_create_pr", proof["safe_next_action"])
+        self.assertIn("exactly matches", proof["matcher_summary"])
+
+    def test_block_proof_reports_competing_and_does_not_claim_adoption(self):
+        assessment = assess_own_branch_adoption(
+            issue_number=420,
+            requested_branch=REQ,
+            existing_branches=[{"name": "feat/issue-420-rogue"}],
+        )
+        proof = self._proof(assessment, REQ)
+        self.assertEqual(proof["adoption_decision"], "BLOCK_COMPETING")
+        self.assertFalse(proof["adopted"])
+        self.assertIsNone(proof["adopted_branch"])
+        self.assertIsNone(proof["adopted_branch_head"])
+        self.assertEqual(proof["competing_branch_check"]["result"], "blocked")
+        self.assertIn(
+            "feat/issue-420-rogue",
+            proof["competing_branch_check"]["competing_branches"],
+        )
+        self.assertIn("fail closed", proof["safe_next_action"])
+
+    def test_no_match_proof_does_not_claim_adoption(self):
+        assessment = assess_own_branch_adoption(
+            issue_number=420,
+            requested_branch=REQ,
+            existing_branches=[{"name": "feat/issue-999-unrelated"}],
+        )
+        proof = self._proof(assessment, REQ)
+        self.assertEqual(proof["adoption_decision"], "NO_MATCH")
+        self.assertFalse(proof["adopted"])
+        self.assertIsNone(proof["adopted_branch"])
+        self.assertEqual(proof["competing_branch_check"]["result"], "clear")
+
+    def test_substring_collision_stays_boundary_safe(self):
+        # issue-42 must not adopt/claim against an issue-420 branch (#440/#477).
+        own = "feat/issue-42-widget"
+        assessment = assess_own_branch_adoption(
+            issue_number=42,
+            requested_branch=own,
+            existing_branches=[
+                {"name": own, "commit_sha": "abc1234"},
+                {"name": "feat/issue-420-server-code-parity"},
+            ],
+        )
+        proof = self._proof(assessment, own)
+        self.assertEqual(proof["adoption_decision"], "ADOPT")
+        self.assertEqual(proof["adopted_branch"], own)
+        self.assertEqual(proof["competing_branch_check"]["competing_branches"], [])
+
+    def test_non_adoption_lock_proof_is_adoption_free(self):
+        proof = build_non_adoption_lock_proof(
+            issue_number=196, branch_name="feat/issue-196-mutations"
+        )
+        self.assertEqual(proof["adoption_decision"], "NO_MATCH")
+        self.assertFalse(proof["adopted"])
+        self.assertIsNone(proof["adopted_branch"])
+        self.assertIsNone(proof["adopted_branch_head"])
+        self.assertEqual(proof["competing_branch_check"]["result"], "clear")
+        self.assertIn("no adoption", proof["safe_next_action"].lower())
+
+
 if __name__ == "__main__":
     unittest.main()