@ikon85/agent-workflow-kit 0.27.1 → 0.28.0

package/scripts/board-sync.py

@@ -1,7 +1,7 @@
 #!/usr/bin/env python3
 """board-sync.py — single GitHub Projects-v2 board-sync / sub-issue helper.
 
-Encapsulates the five board mechanics the planning skills used to inline as bare
+Encapsulates the board mechanics the planning skills used to inline as bare
 `gh` snippets (board-to-waves, to-prd, to-issues):
 
   1. GraphQL-Link    — native parent↔child sub-issue link (`link`)
@@ -9,6 +9,10 @@ Encapsulates the five board mechanics the planning skills used to inline as bare
   3. preview-header  — `GraphQL-Features: sub_issues` on every sub-issue call
   4. Wave-Stempel    — stamp the Wave (number) field (`--wave` on `create`/`add`)
   5. board-sync      — add an issue to the board + set Status/Wave/Cluster/Path fields
+  6. next-wave       — rate-efficient title search with a bounded full-scan fallback
+  7. promotion guard — reject a Wave number already held by another anchor
+  8. item-of         — targeted item/field lookup without scanning the whole board
+  9. archive-done    — dry-run-first, bounded-batch archival of active Done items
 
 Board-specific values (field IDs, status names, labels) are NOT inlined here —
 board_config reads them from the `board-sync:profile` block in
@@ -95,6 +99,8 @@ def _status_roles_or_hint(context: str) -> dict:
     return STATUS_ROLES
 PROJECT_ITEM_LIST_LIMIT = 2000
 GH_TIMEOUT_SECONDS = 15  # a hanging gh prompt must not block a session indefinitely
+PROJECT_ITEM_LIST_TIMEOUT_SECONDS = 60  # full-board reads are slower, but still bounded
+ARCHIVE_DONE_BATCH_SIZE = 30
 
 # Sub-issues GraphQL API is behind a preview feature gate per account.
 SUB_ISSUES_HEADER = "GraphQL-Features: sub_issues"
@@ -127,11 +133,13 @@ class GhError(RuntimeError):
 # --- subprocess seam (the only thing tests monkeypatch) ----------------------
 def _gh(args: list[str]) -> str:
     """Run `gh <args>`, return stdout. Raise GhError on non-zero exit or timeout."""
+    timeout = (PROJECT_ITEM_LIST_TIMEOUT_SECONDS
+               if args[:2] == ["project", "item-list"] else GH_TIMEOUT_SECONDS)
     try:
         result = subprocess.run(["gh", *args], capture_output=True, text=True,
-                                 timeout=GH_TIMEOUT_SECONDS)
+                                 timeout=timeout)
     except subprocess.TimeoutExpired as exc:
-        raise GhError(f"gh {' '.join(args)} timed out after {GH_TIMEOUT_SECONDS}s") from exc
+        raise GhError(f"gh {' '.join(args)} timed out after {timeout}s") from exc
     if result.returncode != 0:
         # `gh api graphql` exits non-zero when the response body carries GraphQL
         # `errors` even alongside a partial `data` (stamp-batch's per-alias
@@ -422,6 +430,10 @@ WAVE_TITLE_PREFIX = wave_title_prefix(_CFG)
 _WAVE_PREFIX_RE = re.compile(
     rf"^\s*{re.escape(WAVE_TITLE_PREFIX)}\s+\d+\s*[—–-]\s*", re.IGNORECASE
 )
+_WAVE_NUMBER_RE = re.compile(rf"^{re.escape(WAVE_TITLE_PREFIX)}\s+(\d+)\b")
+_ANCHOR_TITLE_RE = re.compile(
+    rf"^{re.escape(WAVE_TITLE_PREFIX)}\s+(\d+)\s+—\s+"
+)
 # Leading conventional-commit token (`fix:`, `feat(ui):`, `chore!:`) — anchors
 # don't carry these, so strip it when present. Matches only a lowercase token,
 # so prose titles like "Supabase-Residuen entfernen: …" are left intact.
@@ -443,6 +455,26 @@ def wave_title(current: str, wave: int) -> str:
     return f"{WAVE_TITLE_PREFIX} {wave} — {thema}"
 
 
+def compute_next_wave_from_search(payload: dict) -> Optional[int]:
+    """Return max wave-title number + 1, or None so callers can full-scan."""
+    numbers = []
+    for item in payload.get("items", []):
+        match = _WAVE_NUMBER_RE.match(item.get("title") or "")
+        if match:
+            numbers.append(int(match.group(1)))
+    return max(numbers) + 1 if numbers else None
+
+
+def wave_collision_guard(payload: dict, wave: int, issue: int) -> Optional[str]:
+    """Reject a wave number carried by another anchor; allow replay and leaves."""
+    for item in payload.get("items", []):
+        match = _ANCHOR_TITLE_RE.match(item.get("title") or "")
+        if match and int(match.group(1)) == wave and item.get("number") != issue:
+            return (f"Wave {wave} is already taken by #{item.get('number')} "
+                    f"({item.get('title')!r}); re-read `next-wave` and retry")
+    return None
+
+
 def title_edit_args(issue: int, title: str) -> list[str]:
     """The `gh issue edit` argv that sets an issue's title."""
     return ["issue", "edit", str(issue), "--repo", REPO, "--title", title]
@@ -511,6 +543,43 @@ def _field_value(issue: int, field_id: str) -> Optional[dict]:
     return extract_field_value(data, PROJECT_NODE_ID, field_id)
 
 
+def extract_item_overview(data: dict, project_node_id: str, field_ids: dict) -> Optional[dict]:
+    """Extract one issue's item id and configured field values for this project."""
+    issue = (data.get("data") or {}).get("repository", {}).get("issue") or {}
+    for node in (issue.get("projectItems") or {}).get("nodes") or []:
+        if (node.get("project") or {}).get("id") != project_node_id:
+            continue
+        by_field = {(value.get("field") or {}).get("id"): value
+                    for value in (node.get("fieldValues") or {}).get("nodes") or []}
+        overview = {"itemId": node.get("id")}
+        for name, field_id in field_ids.items():
+            value = by_field.get(field_id)
+            if value is None:
+                overview[name] = None
+            elif "number" in value:
+                overview[name] = value["number"]
+            elif "name" in value:
+                overview[name] = value["name"]
+            else:
+                overview[name] = value.get("text")
+        return overview
+    return None
+
+
+def cmd_item_of(args) -> int:
+    data = _gh_json(["api", "graphql", "-f", f"query={FIELD_VALUE_QUERY}",
+                     "-F", f"owner={PROJECT_OWNER}", "-F", f"repo={REPO_NAME}",
+                     "-F", f"num={args.issue}"])
+    overview = extract_item_overview(data, PROJECT_NODE_ID, {
+        "wave": WAVE_FIELD_ID, "status": STATUS_FIELD_ID, "cluster": CLUSTER_FIELD_ID,
+    })
+    if overview is None:
+        print("NOT-ON-BOARD")
+        return 1
+    print(json.dumps(overview, ensure_ascii=False))
+    return 0
+
+
 def _write_issue_body(issue: int, new_body: str) -> None:
     """Write an issue body via a temp file + `gh issue edit --body-file` — the
     one shared write mechanic for every body-rewriting command in this file."""
@@ -534,13 +603,101 @@ def _add_and_stamp(url, wave, status, cluster, spec_path, plan_path, dry_run) ->
 
 
 # --- commands ----------------------------------------------------------------
-def cmd_next_wave(_args) -> int:
+def cmd_next_wave(args) -> int:
+    if not getattr(args, "scan", False):
+        payload = _gh_json(["api", "-X", "GET", "search/issues",
+                            "-f", f'q=repo:{REPO} is:issue in:title "{WAVE_TITLE_PREFIX}"',
+                            "-f", "per_page=100", "-f", "sort=created", "-f", "order=desc"])
+        next_wave = compute_next_wave_from_search(payload)
+        if next_wave is not None:
+            print(next_wave)
+            return 0
+        print(f"hint: title search found no '{WAVE_TITLE_PREFIX} <N>' issue; "
+              "falling back to the full board scan", file=sys.stderr)
     items = _gh_json(["project", "item-list", str(PROJECT_NUMBER), "--owner", PROJECT_OWNER,
                       "--limit", str(PROJECT_ITEM_LIST_LIMIT), "--format", "json"]).get("items", [])
     print(compute_next_wave(items))
     return 0
 
 
+def extract_done_items(items: list[dict], done_status: str) -> list[dict]:
+    return [item for item in items
+            if item.get("id") and item.get("status") == done_status
+            and not item.get("archived", False) and not item.get("isArchived", False)]
+
+
+def build_archive_mutation(item_ids: list[str]) -> str:
+    calls = []
+    for index, item_id in enumerate(item_ids):
+        calls.append(
+            f"a{index}: archiveProjectV2Item(input: "
+            f"{{projectId: {json.dumps(PROJECT_NODE_ID)}, itemId: {json.dumps(item_id)}}}) "
+            "{ item { id } }"
+        )
+    return "mutation { " + " ".join(calls) + " }"
+
+
+def parse_archive_response(response: dict, item_ids: list[str]) -> tuple[list[str], list[tuple[str, str]]]:
+    data = response.get("data") or {}
+    errors = {error["path"][0]: error.get("message", "unknown GraphQL error")
+              for error in response.get("errors") or [] if error.get("path")}
+    global_errors = [error.get("message", "unknown GraphQL error")
+                     for error in response.get("errors") or [] if not error.get("path")]
+    fallback = "; ".join(global_errors) or "no successful response"
+    succeeded, failed = [], []
+    for index, item_id in enumerate(item_ids):
+        alias = f"a{index}"
+        if data.get(alias) and data[alias].get("item"):
+            succeeded.append(item_id)
+        else:
+            failed.append((item_id, errors.get(alias, fallback)))
+    return succeeded, failed
+
+
+def cmd_archive_done(args) -> int:
+    done_status = resolve_status_role("done", _status_roles_or_hint("archive-done"))
+    payload = _gh_json(["project", "item-list", str(PROJECT_NUMBER),
+                        "--owner", PROJECT_OWNER, "--limit", str(PROJECT_ITEM_LIST_LIMIT),
+                        "--format", "json", "--jq",
+                        "{items: [.items[] | {id, status, archived, isArchived}], "
+                        "totalCount: .totalCount}"])
+    items = payload.get("items", [])
+    total_count = payload.get("totalCount", len(items))
+    if total_count > len(items):
+        raise ValueError(f"project item-list returned {len(items)} of {total_count} items; "
+                         "refusing a partial archive")
+    done_items = extract_done_items(items, done_status)
+    print(f"archive-done: {len(done_items)} of {total_count} active items have status {done_status}")
+    if not done_items:
+        print("archive-done: nothing to archive (idempotent)")
+        return 0
+    chunks = [done_items[start:start + ARCHIVE_DONE_BATCH_SIZE]
+              for start in range(0, len(done_items), ARCHIVE_DONE_BATCH_SIZE)]
+    if not args.apply:
+        for chunk in chunks:
+            _print_dry(["api", "graphql", "-f",
+                        f"query={build_archive_mutation([item['id'] for item in chunk])}"])
+        print("archive-done: dry-run only; pass --apply to archive")
+        return 0
+    succeeded, failed = [], []
+    for chunk in chunks:
+        item_ids = [item["id"] for item in chunk]
+        query = build_archive_mutation(item_ids)
+        try:
+            output = _gh(["api", "graphql", "-f", f"query={query}"])
+        except GhError as exc:
+            output = getattr(exc, "stdout", "") or ""
+            if not output:
+                raise
+        batch_succeeded, batch_failed = parse_archive_response(json.loads(output), item_ids)
+        succeeded += batch_succeeded
+        failed += batch_failed
+    print(f"archive-done: {len(succeeded)} of {len(done_items)} Done items archived")
+    for item_id, message in failed:
+        print(f"  ERROR {item_id}: {message}")
+    return 1 if failed else 0
+
+
 def cmd_parent_of(args) -> int:
     parent = _parent_of(args.issue)
     print(parent if parent is not None else "FREI")
@@ -793,6 +950,13 @@ def cmd_promote(args) -> int:
     if mismatch:
         print(f"error: {mismatch}", file=sys.stderr)
         return 1
+    search = _gh_json(["api", "-X", "GET", "search/issues",
+                       "-f", f'q=repo:{REPO} is:issue in:title "{WAVE_TITLE_PREFIX} {args.wave}"',
+                       "-f", "per_page=100"])
+    collision = wave_collision_guard(search, args.wave, args.issue)
+    if collision:
+        print(f"error: {collision}", file=sys.stderr)
+        return 1
     done: list[str] = []
     try:
         strip = type_labels_to_strip(labels)
@@ -1089,7 +1253,22 @@ def build_parser() -> argparse.ArgumentParser:
     p = argparse.ArgumentParser(prog="board-sync.py", description=__doc__.splitlines()[0])
     sub = p.add_subparsers(dest="command", required=True)
 
-    sub.add_parser("next-wave", help="print the next monotone wave number").set_defaults(func=cmd_next_wave)
+    nw = sub.add_parser("next-wave", help="print the next monotone wave number "
+                                           "(cheap title search; --scan reads the full board)")
+    nw.add_argument("--scan", action="store_true")
+    nw.set_defaults(func=cmd_next_wave)
+
+    archive = sub.add_parser(
+        "archive-done",
+        help="preview archival of active Done items; --apply performs bounded batches",
+    )
+    archive.add_argument("--apply", action="store_true",
+                         help="perform archival (the default is a non-mutating dry-run)")
+    archive.set_defaults(func=cmd_archive_done)
+
+    item = sub.add_parser("item-of", help="targeted item id and field lookup for one issue")
+    item.add_argument("--issue", type=int, required=True)
+    item.set_defaults(func=cmd_item_of)
 
     po = sub.add_parser("parent-of", help="print an issue's parent number or FREI")
     po.add_argument("issue", type=int)

package/scripts/pr-body-check.py

@@ -4,7 +4,7 @@ pr-body-check.py — mechanical guard for the PR-body conventions that were unti
 now prose-only.
 
 Called by `wrapup` Step 0c AFTER the PR has been created/reused, BEFORE the
-merge gate. Turns three instruction-only rules into a check that actually fires:
+merge gate. Turns four instruction-only rules into a check that actually fires:
 
   1. Anker-Slice (Issue HAS a parent) → body MUST contain `Part of #<parent>`
      and MUST NOT contain a close-keyword on the **parent anchor** number
@@ -16,9 +16,12 @@ merge gate. Turns three instruction-only rules into a check that actually fires:
      auto-close never fires, wrapup Step 5b lesson).
   3. `**Retro:**`-Pflichtzeile present in one of the Slice-7 forms
      (`gefahren …` | `übersprungen …`), with a space after the marker.
+  4. Exactly one valid `E2E-NA: <reason>` trailer in the immutable pull-request
+     range requires active `E2E: n/a — <reason>` PR-body evidence.
 
-Scope: this script checks ONLY the closes/Part-of anchor rule and the
-`**Retro:**` line. It does NOT parse or validate `annahme-drift` markers
+Scope: this script checks ONLY the closes/Part-of anchor rule, the
+`**Retro:**` line, and E2E exemption evidence. It does NOT parse or validate
+`annahme-drift` markers
 (those are prose-/judgment-driven in wrapup Step 0c + 5e, deliberately not
 mechanised — R2-F6). The annahme-drift block therefore runs BEFORE this
 check in wrapup Step 0c so the body the script sees is final.
@@ -34,7 +37,7 @@ thin shell. NOT a hook — `wrapup` invokes it (Design).
 
 Usage:
   pr-body-check.py [--branch <name>] [--issue <n>] [--parent <n>|FREI]
-                   [--body-file <path>]
+                   [--body-file <path>] [--base-sha <sha>] [--head-sha <sha>]
 All flags optional; unset → derived from the current branch + live PR via gh.
 
 Audit log: .claude/logs/pr-body-check.log
@@ -47,6 +50,11 @@ from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
 from board_config import ConfigError, load_board_config  # noqa: E402
+from pr_body_e2e import (  # noqa: E402
+    check_e2e_na_line,
+    fetch_has_e2e_na_trailer,
+    fetch_pr_range,
+)
 
 try:
     _CFG = load_board_config()
@@ -122,7 +130,8 @@ def _part_of(body: str, n: int) -> bool:
         rf"\b{PART_OF_RE_SRC}(?::\s*|\s+)#0*{n}(?!\d)", body or "", re.IGNORECASE))
 
 
-def check_pr_body(body: str, issue: int, parent, is_anchor: bool = False):
+def check_pr_body(body: str, issue: int, parent, is_anchor: bool = False,
+                  has_e2e_na_trailer: bool = False):
     """Return a list of violation strings ([] = green).
 
     parent is the anchor issue number, or None for an atomar Leaf.
@@ -165,6 +174,7 @@ def check_pr_body(body: str, issue: int, parent, is_anchor: bool = False):
             "Pflichtzeile `**Retro:** gefahren — …` oder "
             "`**Retro:** übersprungen — <Grund>` fehlt.")
 
+    violations.extend(check_e2e_na_line(body, has_e2e_na_trailer))
     return violations
 
 
@@ -207,12 +217,23 @@ def fetch_is_anchor(number: int) -> bool:
     return "type:cluster" in out.splitlines()
 
 
+def resolve_has_e2e_na(args, branch: str) -> bool:
+    """Explicit test overrides win; otherwise use immutable GitHub PR SHAs."""
+    if args.base_sha or args.head_sha:
+        base_sha, head_sha = args.base_sha, args.head_sha
+    else:
+        base_sha, head_sha = fetch_pr_range(branch)
+    return fetch_has_e2e_na_trailer(base_sha, head_sha)
+
+
 def main() -> int:
     ap = argparse.ArgumentParser(description=__doc__.splitlines()[1])
     ap.add_argument("--branch", help="default: current git branch")
     ap.add_argument("--issue", type=int, help="override branch-derived issue #")
     ap.add_argument("--parent", help="override parent (number or FREI)")
     ap.add_argument("--body-file", help="read PR body from file instead of gh")
+    ap.add_argument("--base-sha", help="override immutable PR base SHA")
+    ap.add_argument("--head-sha", help="override immutable PR head SHA")
     args = ap.parse_args()
 
     branch = args.branch or current_branch()
@@ -244,7 +265,14 @@ def main() -> int:
         parent = fetch_parent(issue)
 
     is_anchor = fetch_is_anchor(issue) if parent is None else False
-    violations = check_pr_body(body, issue, parent, is_anchor=is_anchor)
+    has_e2e_na = resolve_has_e2e_na(args, branch)
+    violations = check_pr_body(
+        body,
+        issue,
+        parent,
+        is_anchor=is_anchor,
+        has_e2e_na_trailer=has_e2e_na,
+    )
     kind = ("Anker-Slice" if parent is not None
             else "Wave-PR" if is_anchor else "Leaf")
     log(f"branch={branch} issue={issue} parent={parent} kind={kind} "

package/scripts/pr_body_e2e.py

@@ -0,0 +1,83 @@
+#!/usr/bin/env python3
+"""Couple a valid E2E-NA trailer to active PR-body evidence."""
+from __future__ import annotations
+
+import json
+import re
+import subprocess
+
+
+E2E_NA_LINE_RE = re.compile(
+    r"^E2E:\s*n/a\s*—\s*\S", re.IGNORECASE | re.MULTILINE
+)
+
+
+def _run(cmd: list[str], timeout=15):
+    try:
+        result = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout)
+        return result.returncode, result.stdout.strip()
+    except Exception:
+        return -1, ""
+
+
+def check_e2e_na_line(body: str, has_e2e_na_trailer: bool) -> list[str]:
+    """Require non-empty body evidence only when a valid trailer exists."""
+    if not has_e2e_na_trailer or E2E_NA_LINE_RE.search(body or ""):
+        return []
+    return [
+        "E2E-NA trailer found in the pull-request range, but required "
+        "`E2E: n/a — <reason>` evidence is missing from the PR body."
+    ]
+
+
+def _git(args: list[str], cwd=None) -> str:
+    result = subprocess.run(
+        ["git", *args], cwd=cwd, capture_output=True, text=True, timeout=15
+    )
+    if result.returncode != 0:
+        raise RuntimeError(result.stderr.strip())
+    return result.stdout
+
+
+def _collect_e2e_na_trailers(base_sha: str, head_sha: str, cwd=None) -> list[str]:
+    raw = _git(
+        [
+            "log",
+            f"{base_sha}..{head_sha}",
+            "--format=%x00%(trailers:key=E2E-NA,unfold)",
+        ],
+        cwd=cwd,
+    )
+    values = []
+    for chunk in raw.split("\x00"):
+        for line in chunk.splitlines():
+            if line.startswith("E2E-NA:"):
+                values.append(line.removeprefix("E2E-NA:").strip())
+    return values
+
+
+def fetch_has_e2e_na_trailer(base_sha, head_sha, cwd=None) -> bool:
+    """Return true for exactly one non-empty trailer; unreadable ranges are false."""
+    if not base_sha or not head_sha:
+        return False
+    try:
+        values = _collect_e2e_na_trailers(base_sha, head_sha, cwd=cwd)
+    except Exception:
+        return False
+    return len(values) == 1 and bool(values[0].strip())
+
+
+def fetch_pr_range(branch: str):
+    """Return GitHub's immutable PR base/head SHAs, or an unreadable range."""
+    rc, out = _run(
+        ["gh", "pr", "view", branch, "--json", "baseRefOid,headRefOid"]
+    )
+    if rc != 0 or not out:
+        return None, None
+    try:
+        data = json.loads(out)
+    except (json.JSONDecodeError, TypeError):
+        return None, None
+    if not isinstance(data, dict):
+        return None, None
+    return data.get("baseRefOid"), data.get("headRefOid")

package/scripts/test_board_sync.py

@@ -0,0 +1,208 @@
+#!/usr/bin/env python3
+"""Behavior tests for bounded board operations; the fake seam never calls GitHub."""
+
+from __future__ import annotations
+
+import io
+import json
+import subprocess
+import unittest
+from contextlib import redirect_stderr, redirect_stdout
+from unittest.mock import patch
+
+import importlib.util
+from pathlib import Path
+
+
+SPEC = importlib.util.spec_from_file_location(
+    "board_sync_operations_test", Path(__file__).with_name("board-sync.py"))
+bs = importlib.util.module_from_spec(SPEC)
+assert SPEC.loader is not None
+SPEC.loader.exec_module(bs)
+
+
+class FakeGh:
+    def __init__(self, responses=None, failures=None):
+        self.responses = responses or {}
+        self.failures = failures or {}
+        self.calls = []
+
+    def __call__(self, args):
+        self.calls.append(args)
+        joined = " ".join(args)
+        for needle, body in self.failures.items():
+            if needle in joined:
+                error = bs.GhError("injected failure")
+                error.stdout = body
+                raise error
+        for needle, body in self.responses.items():
+            if needle in joined:
+                return body
+        return ""
+
+
+def run(fake, argv):
+    old = bs._gh
+    bs._gh = fake
+    out = io.StringIO()
+    try:
+        with redirect_stdout(out):
+            code = bs.main(argv)
+    finally:
+        bs._gh = old
+    return code, out.getvalue()
+
+
+class BoundedCalls(unittest.TestCase):
+    def test_full_board_and_ordinary_calls_have_distinct_clear_timeouts(self):
+        with patch.object(bs.subprocess, "run", side_effect=subprocess.TimeoutExpired("gh", 1)) as call:
+            with self.assertRaisesRegex(bs.GhError, "15s"):
+                bs._gh(["issue", "view", "1"])
+            self.assertEqual(call.call_args.kwargs["timeout"], 15)
+            with self.assertRaisesRegex(bs.GhError, "60s"):
+                bs._gh(["project", "item-list", "3"])
+            self.assertEqual(call.call_args.kwargs["timeout"], 60)
+
+    def test_partial_create_prints_issue_and_replay_safe_repair(self):
+        fake = FakeGh(
+            {"issue list": "[]", "issue create": "https://github.com/x/y/issues/17\n"},
+            {"project item-add": ""},
+        )
+        with patch.object(bs, "REPO", "x/y"):
+            with self.subTest("created issue remains visible"):
+                from tempfile import NamedTemporaryFile
+                with NamedTemporaryFile("w") as body:
+                    body.write("<!-- program-leaf-source: p/1 -->\n")
+                    body.flush()
+                    code, out = run(fake, ["create", "--title", "S", "--body-file", body.name])
+        self.assertEqual(code, 1)
+        self.assertIn("#17 https://github.com/x/y/issues/17", out)
+        self.assertIn("board-sync.py add --issue 17", out)
+        self.assertIn("idempotent", out)
+
+
+class WaveLookup(unittest.TestCase):
+    def test_search_finds_next_wave_without_full_scan(self):
+        fake = FakeGh({"search/issues": json.dumps({"items": [
+            {"title": f"{bs.WAVE_TITLE_PREFIX} 7 — Anchor"},
+            {"title": f"{bs.WAVE_TITLE_PREFIX} 8 / Slice 1 — Leaf"},
+        ]})})
+        code, out = run(fake, ["next-wave"])
+        self.assertEqual((code, out.strip()), (0, "9"))
+        self.assertFalse(any("item-list" in " ".join(c) for c in fake.calls))
+
+    def test_empty_search_falls_back_and_scan_skips_search(self):
+        fake = FakeGh({"search/issues": '{"items":[]}', "item-list": '{"items":[{"wave":4}]}'})
+        with redirect_stderr(io.StringIO()):
+            self.assertEqual(run(fake, ["next-wave"])[1].strip(), "5")
+        scan = FakeGh({"item-list": '{"items":[{"wave":9}]}'})
+        self.assertEqual(run(scan, ["next-wave", "--scan"])[1].strip(), "10")
+        self.assertFalse(any("search/issues" in " ".join(c) for c in scan.calls))
+
+    def test_promotion_refuses_foreign_anchor_but_allows_same_issue(self):
+        foreign = {"items": [{"number": 22, "title": f"{bs.WAVE_TITLE_PREFIX} 7 — Other"}]}
+        message = bs.wave_collision_guard(foreign, 7, 21)
+        self.assertIn("#22", message)
+        self.assertIn("next-wave", message)
+        self.assertIsNone(bs.wave_collision_guard(foreign, 7, 22))
+        leaf = {"items": [{"number": 23, "title": f"{bs.WAVE_TITLE_PREFIX} 7 / Slice 1 — X"}]}
+        self.assertIsNone(bs.wave_collision_guard(leaf, 7, 21))
+
+    def test_promote_collision_fails_before_any_write(self):
+        fake = FakeGh({
+            "--json labels": "",
+            "--json body": "Draft PRD\n",
+            "graphql": '{"data":{"repository":{"issue":{"projectItems":{"nodes":[]}}}}}',
+            "search/issues": json.dumps({"items": [
+                {"number": 22, "title": f"{bs.WAVE_TITLE_PREFIX} 7 — Other"},
+            ]}),
+        })
+        error = io.StringIO()
+        with redirect_stderr(error):
+            code, _ = run(fake, ["promote", "--issue", "21", "--wave", "7"])
+        self.assertEqual(code, 1)
+        self.assertIn("#22", error.getvalue())
+        self.assertFalse(any(c[:2] == ["issue", "edit"] for c in fake.calls))
+
+
+class TargetedLookup(unittest.TestCase):
+    @staticmethod
+    def payload(project):
+        return {"data": {"repository": {"issue": {"projectItems": {"nodes": [{
+            "id": "PVTI_x", "project": {"id": project}, "fieldValues": {"nodes": [
+                {"number": 7, "field": {"id": bs.WAVE_FIELD_ID}},
+                {"name": "Spec", "field": {"id": bs.STATUS_FIELD_ID}},
+            ]},
+        }]}}}}}
+
+    def test_item_of_returns_configured_fields(self):
+        fake = FakeGh({"graphql": json.dumps(self.payload(bs.PROJECT_NODE_ID))})
+        code, out = run(fake, ["item-of", "--issue", "21"])
+        self.assertEqual(code, 0)
+        self.assertEqual(json.loads(out), {"itemId": "PVTI_x", "wave": 7,
+                                           "status": "Spec", "cluster": None})
+
+    def test_item_of_fails_clearly_when_absent(self):
+        payload = {"data": {"repository": {"issue": {"projectItems": {"nodes": []}}}}}
+        code, out = run(FakeGh({"graphql": json.dumps(payload)}),
+                        ["item-of", "--issue", "99"])
+        self.assertEqual((code, out.strip()), (1, "NOT-ON-BOARD"))
+
+
+class ArchiveDone(unittest.TestCase):
+    def item_payload(self, count=1):
+        items = [{"id": f"D{i}", "status": bs.STATUS_ROLES["done"]} for i in range(count)]
+        items += [{"id": "OPEN", "status": bs.STATUS_ROLES["inProgress"]},
+                  {"id": "OLD", "status": bs.STATUS_ROLES["done"], "archived": True}]
+        return json.dumps({"items": items, "totalCount": len(items)})
+
+    def test_archive_defaults_to_dry_run_and_selects_only_active_done(self):
+        fake = FakeGh({"item-list": self.item_payload()})
+        code, out = run(fake, ["archive-done"])
+        self.assertEqual(code, 0)
+        self.assertIn("D0", out)
+        self.assertNotIn("OPEN", out)
+        self.assertNotIn("OLD", out)
+        self.assertFalse(any("archiveProjectV2Item" in " ".join(c) for c in fake.calls))
+
+    def test_apply_batches_at_thirty(self):
+        class BatchGh(FakeGh):
+            def __call__(self, args):
+                self.calls.append(args)
+                if "item-list" in args:
+                    return self.responses["item-list"]
+                count = " ".join(args).count("archiveProjectV2Item")
+                return json.dumps({"data": {f"a{i}": {"item": {"id": f"x{i}"}}
+                                             for i in range(count)}})
+        fake = BatchGh({"item-list": self.item_payload(31)})
+        code, out = run(fake, ["archive-done", "--apply"])
+        self.assertEqual(code, 0)
+        self.assertIn("31 of 31", out)
+        calls = [c for c in fake.calls if "archiveProjectV2Item" in " ".join(c)]
+        self.assertEqual([" ".join(c).count("archiveProjectV2Item") for c in calls], [30, 1])
+
+    def test_truncated_input_refuses_without_mutation(self):
+        fake = FakeGh({"item-list": '{"items":[{"id":"D","status":"Done"}],"totalCount":2}'})
+        err = io.StringIO()
+        with redirect_stderr(err):
+            code, _ = run(fake, ["archive-done", "--apply"])
+        self.assertEqual(code, 1)
+        self.assertIn("partial archive", err.getvalue())
+        self.assertFalse(any("archiveProjectV2Item" in " ".join(c) for c in fake.calls))
+
+    def test_apply_reports_partial_failure_and_empty_replay_is_idempotent(self):
+        body = json.dumps({"data": {"a0": {"item": {"id": "D0"}}, "a1": None},
+                           "errors": [{"path": ["a1"], "message": "already archived"}]})
+        fake = FakeGh({"item-list": self.item_payload(2)}, {"archiveProjectV2Item": body})
+        code, out = run(fake, ["archive-done", "--apply"])
+        self.assertEqual(code, 1)
+        self.assertIn("1 of 2", out)
+        self.assertIn("D1: already archived", out)
+        empty = FakeGh({"item-list": json.dumps({"items": [], "totalCount": 0})})
+        code, out = run(empty, ["archive-done", "--apply"])
+        self.assertEqual(code, 0)
+        self.assertIn("nothing to archive", out)
+
+
+if __name__ == "__main__":
+    unittest.main(verbosity=2)