Extract Implementer clarification into handoff guidance

README.md

@@ -7,8 +7,8 @@ Public source for RelayView-maintained instruction-only role skills and an illus
 | Directory | Status | Role / step | Version |
 | --- | --- | --- | --- |
 | `packages/{planner,implementer,reviewer}-investigation` | Maintained automatic guidance | One matching role / step each | 0.7.0 |
-| `packages/planner-scope` | Maintained default | Planner / planning | 0.8.0 |
-| `packages/implementer-handoff` | Maintained default | Implementer / implementation | 0.2.0 |
+| `packages/planner-scope` | Maintained default | Planner / planning | 0.8.1 |
+| `packages/implementer-handoff` | Maintained default | Implementer / implementation | 0.9.0 |
 | `packages/issue-designer-default` | Maintained default | Designer / design | 0.6.1 |
 | `packages/designer-wayfinder`, `designer-grilling` | Optional manual guidance | Designer / design | 0.6.0 |
 | `packages/designer-prototype` | Optional manual guidance | Designer / design | 0.6.2 |
@@ -35,7 +35,7 @@ Public source for RelayView-maintained instruction-only role skills and an illus
 | `packages/c4-diff` | Optional guidance | Reviewer / review | 0.3.0 |
 | `examples/starter-planner` | Illustrative starter; not a production default | Planner / planning | 0.1.0 |
 
-Only named releases of maintained packages receive RelayView compatibility testing and maintenance. Optional guidance requires explicit role assignment; the Planner and Implementer defaults remain available alongside the pinned Issue Designer default. User forks are maintained by their publishers. This release uses the instruction package schema version 1 admitted by RelayView's Community MVP. It contains only `SKILL.md`, declared `.md`/`.txt` resources, and `relayview-skill.json` within each package. Scripts, executable files, undeclared files, and requested permissions fail checks and owner admission. There is no fixed release calendar: maintained packages are versioned when their content or compatibility changes. A breaking owner contract requires a new compatible maintained release before the product depends on it.
+Only named releases of maintained packages receive RelayView compatibility testing and maintenance. Optional guidance requires explicit role assignment; the Planner and Implementer defaults remain available alongside the pinned Issue Designer default. User forks are maintained by their publishers. Instruction packages use schema version 1, or schema version 2 for a Planner package declaring owner-validated `issueClaim` metadata. Schema 2 accepts a nullable target status label; the owner enforces the claim transition after proved implementation handoff. It contains only `SKILL.md`, declared `.md`/`.txt` resources, and `relayview-skill.json` within each package. Scripts, executable files, undeclared files, and requested permissions fail checks and owner admission. There is no fixed release calendar: maintained packages are versioned when their content or compatibility changes. A breaking owner contract requires a new compatible maintained release before the product depends on it.
 
 ## A named set in RelayView
 

packages/implementer-handoff/SKILL.md

@@ -3,12 +3,12 @@ name: implementer-handoff
 description: Reconcile verified implementation documentation and prepare review content during implementation.
 metadata:
   relayview-display-name: Implementer handoff
-  relayview-version: 0.2.0
+  relayview-version: 0.9.0
 ---
 
 # Implementer handoff
 
-During the assigned implementation step, keep the repository's current-behavior documentation aligned with the code and checks you actually completed. Read the project's documentation rules and the relevant existing contract before editing it. Use the [handoff guide](handoff.md) for the documentation disposition and review content.
+During the assigned implementation step, keep the repository's current-behavior documentation aligned with the code and checks you actually completed. Read the project's documentation rules and the relevant existing contract before editing it. Use the [handoff guide](handoff.md) for implementation clarification, documentation disposition and review content.
 
 Prepare a concise, attributable review handoff when the assigned workflow gives you a place to submit one. Identify the exact candidate, focused checks and their observed results, any manual evidence and its observer, unresolved limitations, and the documentation disposition. A command attempted is not a check passed; report failures and stale evidence explicitly.
 

packages/implementer-handoff/handoff.md

@@ -1,5 +1,11 @@
 # Handoff guide
 
+## Implementation and clarification
+
+Read the relevant files and make focused changes. Use the assigned investigation method for repository discovery; this handoff method owns clarification and report preparation.
+
+Ask the planner for more information when blocked after reasonable investigation. If the final contract appears wrong, explain the mismatch clearly, make the safest local correction if obvious within the authoritative scope, and validate it. Clarification methods guide communication; scope changes require owner authority.
+
 ## Documentation
 
 - Update the current-behavior contract only for behavior verified on the candidate. Keep proposed work clearly proposed.

packages/implementer-handoff/relayview-skill.json

@@ -2,18 +2,18 @@
   "schemaVersion": 1,
   "source": {
     "kind": "first-party",
-    "reference": "v0.2.0"
+    "reference": "v0.9.0"
   },
   "role": "implementer",
   "step": "implementation",
   "files": [
     {
       "path": "SKILL.md",
-      "sha256": "bfeafa2d7780fe2c0bb4206ab9a03acd12804347ceb0f3ffb3e06e1be514c852"
+      "sha256": "a826d49f478018190539843022b83c11e7a034fa3597edcc85b8a57c65ac434d"
     },
     {
       "path": "handoff.md",
-      "sha256": "303c3e792cf0e8da6215e6eeb69f5a2f1f2bd0b67db016160d9e83a970ad95d3"
+      "sha256": "17a32948aeb0e0359c92924219e6c328f3422773d5d878ffbcf0bf2f07a99aeb"
     }
   ]
 }

packages/planner-scope/SKILL.md

@@ -3,7 +3,7 @@ name: planner-scope
 description: Check assigned issue scope, neighboring work, and verification before drafting a Plan.
 metadata:
   relayview-display-name: Planner scope
-  relayview-version: 0.8.0
+  relayview-version: 0.8.1
 ---
 
 # Planner scope

packages/planner-scope/relayview-skill.json

@@ -2,7 +2,7 @@
   "schemaVersion": 2,
   "source": {
     "kind": "first-party",
-    "reference": "v0.8.0"
+    "reference": "v0.8.1"
   },
   "role": "planner",
   "step": "planning",
@@ -12,7 +12,7 @@
   "files": [
     {
       "path": "SKILL.md",
-      "sha256": "7dbd2ace7472a75c69b70ea118333429dfc7d56e5374454724805aa783cc0112"
+      "sha256": "94119fd02a634007f44c227e523802d8f8a7249a97a5526b888d8739401645a2"
     },
     {
       "path": "scope.md",

tests/test_packages.py

@@ -12,6 +12,36 @@ ROOT = Path(__file__).resolve().parents[1]
 
 
 class PackageTests(unittest.TestCase):
+    def test_handoff_clarification_method(self):
+        package = ROOT / "packages/implementer-handoff"
+        check_package(package)
+        text = (package / "handoff.md").read_text()
+        self.assertIn("blocked after reasonable investigation", text)
+        self.assertIn("scope changes require owner authority", text)
+        self.assertNotIn("Trace load order", text)
+
+    def test_schema_two_claim_policy_bounds(self):
+        with tempfile.TemporaryDirectory() as directory:
+            package = Path(directory) / "planner-scope"
+            shutil.copytree(ROOT / "packages/planner-scope", package)
+            sidecar = package / "relayview-skill.json"
+            original = json.loads(sidecar.read_text())
+            for label in (None, "status/review"):
+                manifest = dict(original, issueClaim={"statusLabel": label})
+                sidecar.write_text(json.dumps(manifest))
+                check_package(package)
+            for claim in ({}, [], {"statusLabel": "status/ready-for-agent"},
+                          {"statusLabel": 42}, {"statusLabel": "review"},
+                          {"statusLabel": None, "extra": True}):
+                with self.subTest(claim=claim):
+                    sidecar.write_text(json.dumps(dict(original, issueClaim=claim)))
+                    with self.assertRaises(PackageError):
+                        check_package(package)
+            for role, step in (("implementer", "implementation"), ("reviewer", "review"), ("designer", "design")):
+                sidecar.write_text(json.dumps(dict(original, role=role, step=step)))
+                with self.assertRaises(PackageError):
+                    check_package(package)
+
     def test_planner_scope_presentation_and_claim(self):
         package = ROOT / "packages/planner-scope"
         check_package(package)
@@ -113,7 +143,7 @@ class PackageTests(unittest.TestCase):
                 package = ROOT / "packages" / name
                 manifest = json.loads((package / "relayview-skill.json").read_text())
                 self.assertEqual((manifest["role"], manifest["step"]), (role, step))
-                self.assertEqual(manifest["source"], {"kind": "first-party", "reference": "v0.2.0"})
+                self.assertEqual(manifest["source"], {"kind": "first-party", "reference": "v0.8.1" if name == "planner-scope" else "v0.2.0"})
                 self.assertIn(resource, [item["path"] for item in manifest["files"]])
                 self.assertIn(marker, (package / "SKILL.md").read_text() + (package / resource).read_text())