claude-dev-env 2.12.0 → 2.13.0

package/skills/imagegen/scripts/test_imagegen.py

@@ -0,0 +1,204 @@
+"""Focused tests for exact-resolution image generation."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import sys
+from collections.abc import Mapping, Sequence
+from io import BytesIO
+from pathlib import Path
+
+import pytest
+from PIL import Image
+
+sys.path.insert(0, str(Path(__file__).parent))
+
+import imagegen_core
+from imagegen_core import (
+    ImagegenError,
+    ImageSize,
+    build_oauth_environment,
+    decode_image,
+    download_https_image,
+    generate_image,
+    parse_size,
+    publish_artifact,
+    resize_image,
+)
+
+
+def make_png(image_size: tuple[int, int]) -> bytes:
+    """Create real PNG bytes for provider-boundary tests."""
+    destination = BytesIO()
+    Image.new("RGB", image_size, "purple").save(destination, format="PNG")
+    return destination.getvalue()
+
+
+def test_native_output_preserves_source_bytes_and_receipt(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    source_bytes = make_png((2880, 2880))
+    monkeypatch.setenv("OPENAI_API_KEY", "present")
+    provider_payload = b'{"data":[{"b64_json":"' + base64.b64encode(source_bytes) + b'"}]}'
+    receipt = generate_image("native", "openai-api", ImageSize(2880, 2880), tmp_path / "native.png", "forbid", False, transport=lambda _url, _body, _headers: provider_payload)
+    assert (tmp_path / "native.png").read_bytes() == source_bytes
+    assert receipt["transformation"] == "native"
+    assert receipt["source_sha256"] == hashlib.sha256(source_bytes).hexdigest()
+
+
+def test_oauth_output_resizes_and_strips_api_key(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("OPENAI_API_KEY", "secret")
+    captured_environment: dict[str, str] = {}
+
+    def runner(_arguments: Sequence[str], work_directory: Path, environment: Mapping[str, str]) -> None:
+        captured_environment.update(environment)
+        (work_directory / "generated.png").write_bytes(make_png((1254, 1254)))
+
+    receipt = generate_image("resize", "codex-oauth", ImageSize(2880, 2880), tmp_path / "resized.png", "allow", False, runner=runner)
+    assert decode_image((tmp_path / "resized.png").read_bytes()) == ImageSize(2880, 2880)
+    assert receipt["transformation"] == "resized"
+    assert "OPENAI_API_KEY" not in captured_environment
+
+
+@pytest.mark.parametrize("invalid_size", ("2880", "2880x1440", "2881x2881", "3841x3841", "3840x3840"))
+def test_invalid_sizes_fail(invalid_size: str) -> None:
+    with pytest.raises(ImagegenError):
+        parse_size(invalid_size)
+
+
+@pytest.mark.parametrize("valid_size", ("256x256", "512x512", "1028x1028", "2880x2880"))
+def test_final_sizes_are_independent_from_native_api_sizes(valid_size: str) -> None:
+    assert parse_size(valid_size).as_text() == valid_size
+
+
+def test_openai_unsupported_size_fails_before_authentication(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+
+    with pytest.raises(ImagegenError, match="resize-policy"):
+        generate_image("prompt", "openai-api", ImageSize(1028, 1028), tmp_path / "artifact.png", "forbid", False)
+
+
+def test_openai_native_size_requires_api_key(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+
+    with pytest.raises(ImagegenError, match="OPENAI_API_KEY"):
+        generate_image("prompt", "openai-api", ImageSize(2880, 2880), tmp_path / "artifact.png", "forbid", False)
+
+
+def test_openai_unsupported_size_requests_valid_provider_size_before_resize(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("OPENAI_API_KEY", "present")
+    request_sizes: list[str] = []
+    request_formats: list[str] = []
+    source_bytes = make_png((2048, 2048))
+    provider_payload = b'{"data":[{"b64_json":"' + base64.b64encode(source_bytes) + b'"}]}'
+
+    def transport(_url: str, body: bytes, _headers: Mapping[str, str]) -> bytes:
+        request_payload = json.loads(body)
+        request_sizes.append(request_payload["size"])
+        request_formats.append(request_payload["output_format"])
+        return provider_payload
+
+    receipt = generate_image("prompt", "openai-api", ImageSize(1028, 1028), tmp_path / "artifact.png", "allow", False, transport=transport)
+
+    assert request_sizes == ["2048x2048"]
+    assert request_formats == ["png"]
+    assert receipt["source_size"] == "2048x2048"
+    assert receipt["final_size"] == "1028x1028"
+    assert receipt["transformation"] == "resized"
+
+
+def test_oauth_environment_strips_api_key(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("OPENAI_API_KEY", "secret")
+    assert "OPENAI_API_KEY" not in build_oauth_environment()
+
+
+def test_library_validates_square_size_and_png_destination(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.delenv("OPENAI_API_KEY", raising=False)
+
+    with pytest.raises(ImagegenError, match="size exceeds"):
+        generate_image("prompt", "openai-api", ImageSize(1028, 1024), tmp_path / "artifact.png", "forbid", False)
+    with pytest.raises(ImagegenError, match=".png"):
+        generate_image("prompt", "openai-api", ImageSize(2880, 2880), tmp_path / "artifact.jpg", "forbid", False)
+
+
+def test_http_provider_image_url_is_rejected() -> None:
+    with pytest.raises(ImagegenError, match="HTTPS"):
+        download_https_image("http://example.invalid/image.png")
+
+
+def test_provider_image_url_redirects_are_rejected() -> None:
+    handler = imagegen_core._RejectRedirectHandler()
+    with pytest.raises(ImagegenError, match="redirects"):
+        handler.redirect_request(None, None, 302, "Found", {}, "https://example.invalid/other.png")
+
+
+def test_non_png_provider_bytes_are_rejected() -> None:
+    destination = BytesIO()
+    Image.new("RGB", (16, 16), "purple").save(destination, format="JPEG")
+
+    with pytest.raises(ImagegenError, match="PNG"):
+        decode_image(destination.getvalue())
+
+
+@pytest.mark.parametrize("artifact_names", ((), ("one.png", "two.png")))
+def test_missing_or_multiple_artifacts_fail(tmp_path: Path, artifact_names: tuple[str, ...]) -> None:
+    def runner(_arguments: Sequence[str], work_directory: Path, _environment: Mapping[str, str]) -> None:
+        for each_artifact_name in artifact_names:
+            (work_directory / each_artifact_name).write_bytes(make_png((1254, 1254)))
+
+    with pytest.raises(ImagegenError, match="exactly one"):
+        generate_image("prompt", "codex-oauth", ImageSize(2880, 2880), tmp_path / "artifact.png", "allow", False, runner=runner)
+
+
+def test_mismatched_aspect_ratio_is_rejected(tmp_path: Path) -> None:
+    def runner(_arguments: Sequence[str], work_directory: Path, _environment: Mapping[str, str]) -> None:
+        (work_directory / "generated.png").write_bytes(make_png((1254, 1000)))
+
+    with pytest.raises(ImagegenError, match="square"):
+        generate_image("prompt", "codex-oauth", ImageSize(2880, 2880), tmp_path / "artifact.png", "allow", False, runner=runner)
+
+
+def test_transparency_survives_native_publication(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    destination = BytesIO()
+    Image.new("RGBA", (16, 16), (10, 20, 30, 0)).save(destination, format="PNG")
+    monkeypatch.setenv("OPENAI_API_KEY", "present")
+    provider_payload = b'{"data":[{"b64_json":"' + base64.b64encode(destination.getvalue()) + b'"}]}'
+    generate_image("transparent", "openai-api", ImageSize(16, 16), tmp_path / "transparent.png", "allow", False, transport=lambda _url, _body, _headers: provider_payload)
+    with Image.open(tmp_path / "transparent.png") as image:
+        assert image.mode == "RGBA"
+        assert image.getpixel((0, 0)) == (10, 20, 30, 0)
+
+
+def test_overwrite_refusal_and_cleanup(tmp_path: Path) -> None:
+    output_path = tmp_path / "existing.png"
+    output_path.write_bytes(make_png((16, 16)))
+    with pytest.raises(ImagegenError, match="already exists"):
+        publish_artifact(output_path, output_path.read_bytes(), {"transformation": "native"}, False)
+    assert not list(tmp_path.glob("*.tmp"))
+
+
+def test_publication_rolls_back_when_receipt_replace_fails(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    destination_path = tmp_path / "artifact.png"
+    original_replace = imagegen_core.os.replace
+    replacement_count = 0
+
+    def replace_with_failure(source: Path, target: Path) -> None:
+        nonlocal replacement_count
+        replacement_count += 1
+        if replacement_count == 2:
+            raise OSError("receipt replacement failed")
+        original_replace(source, target)
+
+    monkeypatch.setattr(imagegen_core.os, "replace", replace_with_failure)
+    with pytest.raises(ImagegenError, match="publication failed"):
+        publish_artifact(destination_path, make_png((16, 16)), {"transformation": "native"}, False)
+    assert not destination_path.exists()
+    assert not destination_path.with_suffix(".json").exists()
+    assert not list(tmp_path.glob("*.tmp"))
+
+
+def test_resize_and_decode_have_expected_hashes() -> None:
+    source_bytes = make_png((1254, 1254))
+    final_bytes = resize_image(source_bytes, ImageSize(2880, 2880))
+    assert decode_image(final_bytes) == ImageSize(2880, 2880)
+    assert hashlib.sha256(source_bytes).hexdigest() != hashlib.sha256(final_bytes).hexdigest()

package/skills/orchestrator/SKILL.md

@@ -232,7 +232,7 @@ workflow resume is available.
 | Work | Agent type | Model |
 |---|---|---|
 | Feature, bug, and refactor coding | `clean-coder` | `sonnet` on a Claude host; the sonnet-equivalent id the worker-model resolver prints on a third-party host |
-| Verification passes | `code-verifier` | `sonnet` on a Claude host; the sonnet-equivalent id the worker-model resolver prints on a third-party host |
+| Review and verification | `code-quality-agent` | `sonnet` on a Claude host; the sonnet-equivalent id the worker-model resolver prints on a third-party host |
 | Script runs, GitHub posting, and backfill driving | `general-purpose` runner | `sonnet` on a Claude host; the sonnet-equivalent id the worker-model resolver prints on a third-party host |
 | PR descriptions | `pr-description-writer` | `haiku`, with file-list grounding check |
 | Fan-out searches and checklist verification reads | `Explore` | `haiku`; use `sonnet` when judgment-heavy |
@@ -265,8 +265,7 @@ Routing rules:
   system, with no second one.
 - Resume a warm workflow agent before creating a new workflow run when
   the warm agent holds the relevant context.
-- `clean-coder` owns code edits. `code-verifier` owns verification. The
-  same workflow agent never grades work it wrote.
+- Review and verification workflows apply the [review guide](../reviews/SKILL.md#review-workflow).
 - PR-description workflows include the actual changed-file list in the
   prompt and verify the final body against that file list before posting
   or returning it.
@@ -363,4 +362,3 @@ no open work remains, run `set --status done` before any re-arm attempt.
 ## File-backed run ledger
 
 When host task tools are absent, reconcile delegated work through `scripts/grok_run_ledger.py` under the run-state directory (stable task ids, one live owner, unique advisor sessions, dependency blocking, snapshot-drift reopening).
-

package/skills/plan-to-pr/SKILL.md

@@ -57,8 +57,7 @@ Refuse the first matching case and stop:
 - A requested change spans files outside the packet's allowed file set.
 - A task contains more than one deliverable, acceptance check, or commit.
 - A required task tool, verifier, model tier, advisor, review path, or gate is unavailable.
-- The user asks to bypass verification, `verified_commit_gate`, independent
-  review, final validation, or a publication gate.
+- The user asks to bypass verification, review under the [review guide](../reviews/SKILL.md#review-workflow), final validation, or a publication gate.
 
 Return exactly: `Plan-to-PR blocked: <missing input or capability>.`
 
@@ -105,8 +104,8 @@ For each seeded task:
 1. The orchestrator issues the standalone task ticket.
 2. One worker implements one deliverable within the ticket's allowed files.
 3. The worker runs the one acceptance check and reports exact output and blockers.
-4. A fresh verifier checks the task diff, baseline, named gates, and ticket-to-diff
-   scope. It must pass `verified_commit_gate` for the exact surface.
+4. Review and verify the task diff, baseline, named checks, and ticket-to-diff
+   scope under the [review guide](../reviews/SKILL.md#review-workflow).
 5. The orchestrator creates exactly one commit and records its hash.
 
 No task borrows files, acceptance checks, or commit history from another task.
@@ -114,7 +113,7 @@ Unrelated changes remain untouched and uncommitted.
 
 ## Review and repair
 
-Before every commit, require fresh verification and `verified_commit_gate`.
+Before every commit, record fresh verification and review under the [review guide](../reviews/SKILL.md#review-workflow).
 After the commit, a separate fast low-effort Luna review worker runs native
 findings-only correctness review at `/e-code-review low`. The review returns
 findings only and has no repair flag.
@@ -128,8 +127,8 @@ gate after cleanup.
 ## Final validation and publication
 
 The Luna max final validator maps every commit to one packet task and checks
-cumulative behavior, the allowed-file ledger, acceptance checks, verifier
-output, `verified_commit_gate` evidence, and post-commit review records. Any
+cumulative behavior, the allowed-file ledger, acceptance checks, verification
+output, and post-commit review records. Any
 unmapped commit, missing record, failed gate, or unresolved finding blocks
 publication.
 

package/skills/plan-to-pr/reference/final-validation-tasks.md

@@ -7,7 +7,7 @@ PASS, FAIL plus file and line evidence, or N/A plus a reason.
 2. Confirm every task record has required identity, files, acceptance, and commit fields.
 3. Confirm every committed task has native findings-only review and separate repair records.
 4. Confirm every repair has acceptance output, fresh exact-surface verification, and an amended commit before the next review.
-5. Confirm all review records are clean and all verifier records pass.
+5. Confirm all review records are clean and all verification records are present.
 6. Confirm the complete allowed-file ledger contains no extra changed files.
 7. Confirm final validation and workflow self-audit evidence are present before release.
 8. Confirm the finalized PR branch receives Luna max `/e-simplify` cleanup with

package/skills/plan-to-pr/reference/process-inventory.md

@@ -11,10 +11,10 @@ judgment remains in the hub or companion reference.
 | Seed implementation work after packet approval | deterministic | `task-seed:reference/task-seeds.md` | Host task IDs, packet path, and evidence | task-tool |
 | Record task fields | deterministic | `reference/run-record.schema.json` and `scripts/validate_protocol.py` | Validator output and exit code | `scripts/test_validate_protocol.py` |
 | Implement one deliverable | judgment | `SKILL.md` | Worker report and diff | N/A: implementation choice |
-| Verify exact surface | deterministic | `task-seed:reference/task-seeds.md` | Verifier output and `verified_commit_gate` | task-tool |
+| Verify exact surface | deterministic | `task-seed:reference/task-seeds.md` | Verification output and [review guide](../../reviews/SKILL.md#review-workflow) | task-tool |
 | Review committed task | deterministic | `reference/review-loop.md` | Findings-only native review record | `test_task_ticket_contract.py` |
 | Repair confirmed findings | deterministic | `reference/review-loop.md` | Separate repair record and confirmed findings | `test_task_ticket_contract.py` |
-| Decide whether a finding is confirmed | judgment | `reference/review-loop.md` | Repair record names the confirmed finding | N/A: review judgment |
+| Decide whether a finding is confirmed | judgment | [review guide](../../reviews/SKILL.md#review-judgment) | Repair record names the confirmed finding | N/A: review judgment |
 | Repeat until clean | borderline | `reference/review-loop.md` | Amended commit and clean review record | `test_task_ticket_contract.py` |
 | Validate cumulative release | deterministic | `task-seed:reference/final-validation-tasks.md` | Final validator task evidence | task-tool |
 | Self-audit the workflow | deterministic | `task-seed:reference/self-audit-tasks.md` | Self-audit task evidence | task-tool |

package/skills/plan-to-pr/reference/review-loop.md

@@ -6,7 +6,7 @@ Run this loop for every committed task. Store each pass in the task record.
 2. It invokes the native findings-only `/e-code-review low` correctness
    capability; the review has no repair flag.
 3. Record resolved model, effort, command, findings, repair status, and surface
-   hash. Missing native review or verifier capability fails closed.
+   hash. Apply the [review guide](../../reviews/SKILL.md#review-workflow) to every finding.
 4. A separate fast low-effort Luna repair worker applies only confirmed findings.
 5. Rerun the task acceptance check and fresh exact-surface verification.
 6. Amend the task commit and repeat the native review until clean.
@@ -14,7 +14,7 @@ Run this loop for every committed task. Store each pass in the task record.
 ## Accepted records
 
 Clean means the native review reports no findings for the exact committed
-surface. A repaired pass is not accepted until acceptance and fresh verifier
+surface. A repaired pass is not accepted until acceptance and fresh verification
 output are recorded against the amended commit.
 
 ## Example

package/skills/plan-to-pr/reference/run-record.schema.json

@@ -22,6 +22,6 @@
     "finding": {"type": "object", "additionalProperties": false, "required": ["finding", "disposition"], "properties": {"finding": {"type": "string", "minLength": 1}, "disposition": {"enum": ["confirmed", "dismissed"]}}},
     "review_record": {"type": "object", "additionalProperties": false, "required": ["resolved_model", "effort", "command", "findings", "repair_status", "surface_hash", "findings_only", "has_repair_flag"], "properties": {"resolved_model": {"type": "string", "minLength": 1}, "effort": {"type": "string", "minLength": 1}, "command": {"type": "string", "minLength": 1}, "findings": {"type": "array", "items": {"$ref": "#/$defs/finding"}}, "repair_status": {"type": "string", "minLength": 1}, "surface_hash": {"type": "string", "minLength": 1}, "findings_only": {"const": true}, "has_repair_flag": {"const": false}}},
     "repair_record": {"type": "object", "additionalProperties": false, "required": ["resolved_model", "effort", "confirmed_findings", "repair_status", "surface_hash"], "properties": {"resolved_model": {"type": "string", "minLength": 1}, "effort": {"type": "string", "minLength": 1}, "confirmed_findings": {"type": "array", "items": {"type": "string", "minLength": 1}}, "repair_status": {"type": "string", "minLength": 1}, "surface_hash": {"type": "string", "minLength": 1}}},
-    "verification_record": {"type": "object", "additionalProperties": false, "required": ["acceptance_output", "verifier_output", "verified_commit_gate", "surface_hash"], "properties": {"acceptance_output": {"type": "string", "minLength": 1}, "verifier_output": {"type": "string", "minLength": 1}, "verified_commit_gate": {"type": "string", "minLength": 1}, "surface_hash": {"type": "string", "minLength": 1}}}
+    "verification_record": {"type": "object", "additionalProperties": false, "required": ["acceptance_output", "verification_output", "surface_hash"], "properties": {"acceptance_output": {"type": "string", "minLength": 1}, "verification_output": {"type": "string", "minLength": 1}, "surface_hash": {"type": "string", "minLength": 1}}}
   }
 }

package/skills/plan-to-pr/reference/task-seeds.md

@@ -7,7 +7,7 @@ equivalent before implementation. Mark it complete only with evidence.
 2. Capture the baseline and create one task record from the run-record schema.
 3. Implement the single deliverable within the allowed file set.
 4. Run the acceptance check and record its exact output.
-5. Run fresh exact-surface verification and `verified_commit_gate`.
+5. Run fresh exact-surface verification and apply the [review guide](../../reviews/SKILL.md#review-workflow).
 6. Create exactly one task commit and record its identity.
 7. Run the separate native review and record findings-only output.
 8. Run separate Luna repair only for confirmed findings; rerun acceptance and

package/skills/plan-to-pr/reference/task-ticket.md

@@ -17,13 +17,12 @@ commits.
 | Worker route | The model role and selected route from `reference/model-routing.md`; planner and final-validator records include Luna max plus Sol xhigh advisor evidence, and orchestrator records the max route |
 | Commit record | Exactly one commit hash for this ticket |
 | Review record | Separate fast low-effort Luna review output that invokes native `/e-code-review low` and returns findings only, followed by separate fast low-effort Luna repair output, including resolved model, effort, command, findings, repair status, and surface hash |
-| Verification record | Fresh verifier output and `verified_commit_gate` result for the exact surface |
+| Verification record | Fresh verification output for the exact surface and review under the [review guide](../../reviews/SKILL.md#review-workflow) |
 
 ## Execution contract
 
 The worker changes only the allowed files, runs the acceptance check, and reports
-the exact output. A fresh verifier checks the ticket against the diff before one
-commit is created. The commit hash is recorded before the separate review pass.
+the exact output. Review and verification follow the [review guide](../../reviews/SKILL.md#review-workflow) before one commit is created. The commit hash is recorded before the separate review pass.
 
 ## Review and completion contract
 
@@ -33,6 +32,6 @@ repair flag. A separate fast low-effort Luna repair worker applies only confirme
 the resolved model, effort, command, findings, repair status, and surface hash.
 Confirmed repairs require the acceptance check and fresh exact-surface verification
 again; amend the task commit and repeat the native review until clean. Missing
-native review or required verifier capability fails closed. The
+native review fails closed. The
 final validator maps the commit to this ticket and rejects missing or extra
 records.

package/skills/plan-to-pr/scripts/config/constants.py

@@ -174,8 +174,7 @@ ALL_REPAIR_FIELDS: tuple[str, ...] = (
 )
 ALL_VERIFICATION_FIELDS: tuple[str, ...] = (
     "acceptance_output",
-    "verifier_output",
-    "verified_commit_gate",
+    "verification_output",
     "surface_hash",
 )
 ALL_REVIEW_TEXT_FIELDS: tuple[str, ...] = (

package/skills/plan-to-pr/scripts/test_validate_protocol.py

@@ -20,7 +20,7 @@ validate_record = VALIDATE_PROTOCOL_MODULE.validate_record
 
 
 def valid_record() -> dict[str, object]:
-    verification = {"acceptance_output": "passed: pytest", "verifier_output": "passed: clean", "verified_commit_gate": "passed: exact surface", "surface_hash": "a" * 64}
+    verification = {"acceptance_output": "passed: pytest", "verification_output": "passed: clean", "surface_hash": "a" * 64}
     return {
         "task_identity": "task-3", "deliverable": "validator", "allowed_files": ["validator.py"],
         "acceptance_check": "pytest", "baseline": "clean", "worker_route": "implementation worker; effort=low", "commit": "a1b2c3d",

package/skills/plan-to-pr/test_skill_contract.py

@@ -90,7 +90,7 @@ def test_skill_contract_enforces_task_commit_and_review_order() -> None:
     skill_text = read_skill_text()
 
     assert EXPECTED_TASK_PROTOCOL_HEADING in skill_text
-    assert "fresh verification and `verified_commit_gate`" in skill_text
+    assert "fresh verification and review under the [review guide]" in skill_text
     assert (
         "native\nfindings-only correctness review at `/e-code-review low`" in skill_text
     )
@@ -163,7 +163,7 @@ def test_skill_contract_references_future_fixed_artifacts_without_copying_tables
 
 def test_skill_contract_companion_reference_paths_exist() -> None:
     skill_text = read_skill_text()
-    local_reference_paths = re.findall(r"\]\(([^)]+)\)", skill_text)
+    local_reference_paths = [each_path.split("#", maxsplit=1)[0] for each_path in re.findall(r"\]\(([^)]+)\)", skill_text)]
     repository_paths = [
         each_path
         for each_path in local_reference_paths

package/skills/pr-converge/SKILL.md

@@ -168,9 +168,8 @@ when `$CLAUDE_JOB_DIR` is gone.
 
 Fields: `phase`, `tick_count`, `bugbot_clean_at`, `code_review_clean_at`,
 `bugteam_clean_at`, `copilot_clean_at`, `merge_state_status`, `current_head`,
-`bugbot_acknowledged_at`, `bugbot_down`, `copilot_down`,
-`bugteam_skill_invoked_at_head`, `bugteam_skill_invoked_at_tick`,
-`agents_session_id`, `persistent_agents`.
+`bugbot_acknowledged_at`, `bugbot_down`, `copilot_down`, `agents_session_id`,
+`persistent_agents`.
 
 ## Persistent per-step agents
 
@@ -190,19 +189,17 @@ the `persistent_agents` map
   resolver-supplied sonnet-equivalent on third-party hosts. The `name`
   makes the agent a persistent teammate
   that idles awaiting messages. Record `{agent_id, created_tick,
-  last_used_tick}` under the step key. Keep the spawn prompt fix-shaped,
-  never audit-shaped: the `pr_converge_bugteam_enforcer` hook blocks
-  audit-shaped clean-coder spawns during the BUGTEAM phase.
+  last_used_tick}` under the step key. Keep the spawn prompt focused on the
+  current fix. Step 6 sends audit judgment through the
+  [review guide](../reviews/SKILL.md#review-workflow).
 - **Stale or dead id:** on a `SendMessage` failure, or no acknowledgment
   within one bounded wait, drop the map entry, spawn a fresh named agent,
   record it, and continue the tick. Never abort a tick on a stale id;
   never retry the same dead id.
 - **Fresh every round (never persisted):** the Step 5 host-aware
   `invoke_code_review.py` / `/code-review ultra --fix` pass and the Step 6
-  bugteam audit (unbiased eyes each round; the enforcer needs the formal
-  Skill call), and every `code-verifier` — a named code-verifier never fires
-  `SubagentStop`, so no verdict mints (see the named-`code-verifier` entry
-  in the Gotchas list below).
+  bugteam audit. Apply the [review guide](../reviews/SKILL.md#review-workflow)
+  to each review pass.
 - **Shutdown:** at loop end (convergence or a stop condition), send each
   persistent agent a shutdown request and clear `persistent_agents` before
   the `pr-loop-lifecycle` Close.
@@ -263,7 +260,6 @@ post a fresh PR in a fresh branch based on origin main to the user.
   [Step 1.5](reference/per-tick.md). Skipping this reviews and edits the
   wrong repo. The route is routine and automatic — never a material fork
   to pause on.
-- **A named/teammate `code-verifier` never mints a verdict** — In a background-job session, an `Agent`-tool `code-verifier` spawned with a `name` (or otherwise as a persistent teammate) goes idle/"available" awaiting messages rather than terminating, so its `SubagentStop` never fires. `verifier_verdict_minter.py` mints the verdict only on `SubagentStop`, so no verdict file is written and `verified_commit_gate` blocks the `git commit`/`git push` with "no passing verification verdict" even though the verifier emitted `all_pass`. A `shutdown_request` is ignored and `TaskStop` cannot resolve the teammate's id. Spawn the code-verifier as a one-shot agent with NO `name` (a plain async `Agent` call) so it runs to completion and fires `SubagentStop`, minting the verdict bound to the live surface. Keep the work tree frozen between verification and the commit so the minted surface hash still matches.
 
 ## Progress checklist
 
@@ -333,7 +329,7 @@ round as converged. This rule holds every tick, every loop, every PR.
       - [ ] **clean on `current_head`** → zero unresolved threads (else fix + resolve first)
             → `bugbot_clean_at = current_head` → Step 7
       - [ ] **no review / commit_id mismatch** → `reviewer-gates` Bugbot flow (Gate 3):
-            silent pass → stamp + Step 7; queued/triggered → ScheduleWakeup 360s or portable in-session poll → Step 4;
+            silent pass → Step 7; queued/triggered → ScheduleWakeup 360s or portable in-session poll → Step 4;
             down → `bugbot_down = true` → Step 7
 
 - [ ] **Step 5: CODE-REVIEW — static sweep, review, fix, advance**
@@ -373,9 +369,10 @@ round as converged. This rule holds every tick, every loop, every PR.
       See: [`reference/per-tick.md` § Step 2 BUGTEAM](reference/per-tick.md);
       [`../bugteam/SKILL.md`](../bugteam/SKILL.md).
       Pre-condition: `code_review_clean_at == current_head`.
-      Mandatory: `Skill({skill: "bugteam", args: "<PR URL>"})` this tick
-      (enforcer-blocked otherwise; `qbug` is not a substitute). Scope: FULL
-      `origin/main...HEAD` diff. Re-resolve HEAD after bugteam.
+      Mandatory: `Skill({skill: "bugteam", args: "<PR URL>"})` this tick.
+      Use the [review guide](../reviews/SKILL.md#review-workflow) for its
+      judgment. `qbug` is not a substitute. Scope: FULL `origin/main...HEAD`
+      diff. Re-resolve HEAD after bugteam.
 
       - [ ] **bugteam pushed** → verify threads replied + resolved → reset markers
             → `phase = CODE_REVIEW` → ScheduleWakeup 360s or portable in-session poll → Step 5
@@ -392,7 +389,7 @@ round as converged. This rule holds every tick, every loop, every PR.
       before these gates run. Count unresolved threads before each gate.
       Every gate records evidence; gate (f) cites evidence from (a)–(e).
 
-      - [ ] **(a) Copilot findings** — fetch Copilot on `current_head`; dirty → fix + return to Step 5; clean → stamp `copilot_clean_at`; absent → continue; when `copilot_down`, skip
+      - [ ] **(a) Copilot findings** — fetch Copilot on `current_head`; dirty → fix + return to Step 5; clean → record `copilot_clean_at`; absent → continue; when `copilot_down`, skip
       - [ ] **(b) Claude reviewer** — fetch Claude on `current_head`; dirty → fix + return to Step 5; clean or absent → continue
       - [ ] **(c) Mergeability** — `mergeable_state == "clean"` and `mergeable == true`; dirty → rebase + return to Step 1; blocked/behind/unknown/unstable → hard blocker
       - [ ] **(d) Post-convergence Copilot request** — request Copilot when not pending and not `copilot_down`; enter `COPILOT_WAIT` (Step 7a); when `copilot_down`, skip to (e)

package/skills/pr-converge/reference/progress-checklist.md

@@ -70,7 +70,7 @@ round as converged. This rule holds every tick, every loop, every PR.
       - [ ] **clean on `current_head`** → zero unresolved threads (else fix + resolve first)
             → `bugbot_clean_at = current_head` → Step 7
       - [ ] **no review / commit_id mismatch** → `reviewer-gates` Bugbot flow (Gate 3):
-            silent pass → stamp + Step 7; queued/triggered → 360s wakeup → Step 4;
+            silent pass → Step 7; queued/triggered → 360s wakeup → Step 4;
             down → `bugbot_down = true` → Step 7
 
 - [ ] **Step 5: CODE-REVIEW — static sweep, review, fix, advance**
@@ -110,9 +110,10 @@ round as converged. This rule holds every tick, every loop, every PR.
       See: [`per-tick.md` § Step 2 BUGTEAM](per-tick.md);
       [`../../bugteam/SKILL.md`](../../bugteam/SKILL.md).
       Pre-condition: `code_review_clean_at == current_head`.
-      Mandatory: `Skill({skill: "bugteam", args: "<PR URL>"})` this tick
-      (enforcer-blocked otherwise; `qbug` is not a substitute). Scope: FULL
-      `origin/main...HEAD` diff. Re-resolve HEAD after bugteam.
+      Mandatory: `Skill({skill: "bugteam", args: "<PR URL>"})` this tick.
+      Use the [review guide](../../reviews/SKILL.md#review-workflow) for its
+      judgment. `qbug` is not a substitute. Scope: FULL `origin/main...HEAD`
+      diff. Re-resolve HEAD after bugteam.
 
       - [ ] **bugteam pushed** → verify threads replied + resolved → reset markers
             → `phase = CODE_REVIEW` → 360s wakeup → Step 5
@@ -129,7 +130,7 @@ round as converged. This rule holds every tick, every loop, every PR.
       before these gates run. Count unresolved threads before each gate.
       Every gate records evidence; gate (f) cites evidence from (a)–(e).
 
-      - [ ] **(a) Copilot findings** — fetch Copilot on `current_head`; dirty → fix + return to Step 5; clean → stamp `copilot_clean_at`; absent → continue; when `copilot_down`, skip
+      - [ ] **(a) Copilot findings** — fetch Copilot on `current_head`; dirty → fix + return to Step 5; clean → record `copilot_clean_at`; absent → continue; when `copilot_down`, skip
       - [ ] **(b) Claude reviewer** — fetch Claude on `current_head`; dirty → fix + return to Step 5; clean or absent → continue
       - [ ] **(c) Mergeability** — `mergeable_state == "clean"` and `mergeable == true`; dirty → rebase + return to Step 1; blocked/behind/unknown/unstable → hard blocker
       - [ ] **(d) Post-convergence Copilot request** — request Copilot when not pending and not `copilot_down`; enter `COPILOT_WAIT` (Step 7a); when `copilot_down`, skip to (e)

package/skills/pr-converge/reference/state-schema.md

@@ -13,10 +13,7 @@ Single-PR `/pr-converge` writes loop state to
 `$CLAUDE_JOB_DIR/pr-converge-state.json`; that file is the source of truth
 for `phase`, heads, counters, status. Multi-PR mode additionally maintains
 `<TMPDIR>/pr-converge-<session_id>/state.json` for orchestrator coordination
-across PRs. Both files share most of the fields below; the
-`bugteam_skill_invoked_at_head` and `bugteam_skill_invoked_at_tick` fields
-live ONLY in the single-PR `$CLAUDE_JOB_DIR/pr-converge-state.json` file
-(see those field entries below for details).
+across PRs. Both files share the fields below.
 
 ## Fields
 
@@ -94,29 +91,6 @@ live ONLY in the single-PR `$CLAUDE_JOB_DIR/pr-converge-state.json` file
   (c) reads this field to decide between "schedule next wakeup" and
   "escalate to bugbot-down".
 - `tick_count`: integer, init `0`. Increment every tick.
-- `bugteam_skill_invoked_at_head`: HEAD SHA (string) at which the formal
-  `Skill({skill: "bugteam"})` was last invoked, or `null`. Stamped by the
-  `pr_converge_bugteam_skill_tracker` hook on every formal bugteam Skill
-  invocation. **On-disk location:** the tracker writes this field to
-  `$CLAUDE_JOB_DIR/pr-converge-state.json` (single-PR mode); it is NOT
-  mirrored into the multi-PR `<TMPDIR>/pr-converge-<session_id>/state.json`
-  file. Operators inspecting these stamps must read the single-PR
-  `pr-converge-state.json` under `$CLAUDE_JOB_DIR`. Reset by overwrite on
-  the next bugteam Skill invocation; staleness is detected by the head/tick
-  equality check rather than by explicit reset. The
-  `pr_converge_bugteam_enforcer` hook reads this field together with
-  `current_head` to confirm the formal Skill registered at the current HEAD
-  before allowing follow-on clean-coder audit-shaped Agent spawns. `qbug`
-  invocations deliberately do NOT update this field.
-- `bugteam_skill_invoked_at_tick`: integer tick number at which the formal
-  bugteam Skill was last invoked, or `null`. Companion to
-  `bugteam_skill_invoked_at_head` and persisted to the same
-  `$CLAUDE_JOB_DIR/pr-converge-state.json` file (single-PR mode only).
-  Reset by overwrite on the next bugteam Skill invocation; staleness is
-  detected by the head/tick equality check rather than by explicit reset.
-  The enforcer requires this value to equal the current `tick_count` so a
-  Skill invocation from a prior tick cannot wave through clean-coder
-  audit-shaped Agent spawns on a later tick at the same HEAD.
 - `agents_session_id`: string or `null`, init `null`. The session id that
   spawned the persistent per-step agents recorded in `persistent_agents`.
   On tick entry, compare it to the current session id: when they differ,

package/skills/pr-loop-cloud-transport/SKILL.md

@@ -89,7 +89,7 @@ Skip the `gh api copilot_internal/user` quota read; treat Copilot quota as unkno
 The `gh`-text hooks read risk from literal `gh ...` command text, and an MCP post carries none, so those checks go quiet in cloud. Before each MCP post, check by hand:
 
 - No volatile scratch path in a post body (job dirs, temp roots, worktrees).
-- A proof-of-work comment carries all five parts the proof standard names.
+- Review comments follow the [comment guide](../comments/SKILL.md#writing-useful-review-comments).
 - A PR title follows Conventional Commits.
 - Markdown bodies go through the structured `body` parameter so backticks show as formatting.
 

package/skills/pr-loop-cloud-transport/reference/identity-and-hooks.md

@@ -26,14 +26,14 @@ Author-keyed logic accounts for the split: a self-PR check keys on the login tha
 
 ## Hooks that still gate a cloud run
 
-The commit and push gates read git commands, which a cloud run still issues through Bash, so they fire normally and the run follows them: `verified_commit_gate`, `session_edit_stage_gate`, `block_main_commit`, `precommit_code_rules_gate`, `test_preflight_check`, and the pre-push base-ref check that needs `origin/HEAD` set (SKILL.md Step 2).
+The commit and push gates read git commands, which a cloud run still issues through Bash, so they fire normally and the run follows them: `session_edit_stage_gate`, `block_main_commit`, `precommit_code_rules_gate`, `test_preflight_check`, and the pre-push base-ref check that needs `origin/HEAD` set (SKILL.md Step 2).
 
 ## Hooks that go quiet on the MCP path
 
-The `gh`-text hooks read risk from literal `gh ...` command text: `pr_description_enforcer`, `gh_body_arg_blocker`, `conventional_pr_title_gate`, `gh_pr_author_enforcer`, the `gh` branch of `volatile_path_in_post_blocker`, and the `gh pr ready` branch of `convergence_gate_blocker`. An MCP post carries no `gh` text, so these checks see nothing to gate while the settings matchers name only the local tool prefix. The run covers the gap by hand before each MCP post — the Step 6 self-check in SKILL.md:
+The `gh`-text hooks read risk from literal `gh ...` command text: `gh_body_arg_blocker`, `conventional_pr_title_gate`, `gh_pr_author_enforcer`, and the `gh` branch of `volatile_path_in_post_blocker`. An MCP post carries no `gh` text, so these checks see nothing to gate while the settings matchers name only the local tool prefix. The run covers the gap by hand before each MCP post — the Step 6 self-check in SKILL.md:
 
 - No volatile scratch path in a post body (job dirs, temp roots, worktrees).
-- A proof-of-work comment carries all five parts the proof standard names.
+- Review comments follow the [review guide](../../reviews/SKILL.md#review-workflow).
 - A PR title follows Conventional Commits.
 - Markdown bodies go through the structured `body` parameter so backticks show as formatting.
 

package/skills/pr-loop-lifecycle/SKILL.md

@@ -44,7 +44,7 @@ Run these in order from the lead session on EVERY exit — converged, cap reache
    ```
    Tolerates already-removed worktrees and missing directories; removal is Windows-safe per `~/.claude/rules/windows-filesystem-safe.md`.
 3. **Clean the working tree.** Return to the session worktree, remove run-scoped scratch files, and leave `git status` clean of run artifacts.
-4. **Rewrite the PR description.** Follow [`reference/teardown-publish-permissions.md` § Publish the final PR description](reference/teardown-publish-permissions.md): capture the cumulative diff and original body, compose the new body directly against `docs/PR_DESCRIPTION_GUIDE.md`, publish via `update_pull_request`, remove the scratch files. On failure, report it and continue — the revoke still runs.
+4. **Update the PR description.** Follow [`reference/teardown-publish-permissions.md` § Publish the final PR description](reference/teardown-publish-permissions.md): capture the cumulative diff and original body, compose it against the [description guide](../descriptions/SKILL.md#required-content), publish via `update_pull_request`, then remove the scratch files.
 5. **Revoke project permissions (always):**
    `python "$HOME/.claude/_shared/pr-loop/scripts/revoke_project_claude_permissions.py"`
    Non-negotiable, including on error exits: leaving the grant in place lets future sessions inherit elevated `.claude/**` access without an explicit opt-in. Run revoke even when earlier close steps partially failed; log cleanup errors separately.

package/skills/pr-loop-lifecycle/reference/teardown-publish-permissions.md

@@ -35,7 +35,7 @@ When the run exits (any reason), run these steps in order from **this** session
 
 After teardown and before permission revoke, the lead rewrites the PR body to the PR's **final cumulative state** — what the change delivers, not the loop's process. This is the **only** PR-write the lead performs (audit and fix comments stay with the agents that produced them).
 
-The lead composes the body text directly against `docs/PR_DESCRIPTION_GUIDE.md` — no agent spawn — so the body passes the `pr_description_enforcer` hook's style audit on the `gh pr edit` that follows.
+The lead composes the body against the [description guide](../../descriptions/SKILL.md#required-content) and publishes it through the GitHub client.
 
 **Steps:**