@quybt93/pcgf 0.0.1

package/.agents/skills/bmad-retrospective/scripts/tests/test_sprint_status.py

@@ -0,0 +1,1579 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["pytest>=8.0", "ruamel.yaml>=0.18"]
+# ///
+"""Corruption-critical tests for sprint-status.py.
+
+Each test runs the script as a subprocess via ``uv run`` against a temp copy of
+an inline fixture, then re-reads the file to assert comments and formatting
+survive and punctuation-heavy action values round-trip intact.
+
+Run: uv run scripts/tests/test_sprint_status.py
+ or: uv run --with pytest --with ruamel.yaml -m pytest scripts/tests/test_sprint_status.py
+"""
+
+import importlib.util
+import json
+import os
+import re
+import stat
+import subprocess
+import sys
+from pathlib import Path
+
+import pytest
+from ruamel.yaml import YAML
+
+SCRIPT = Path(__file__).resolve().parents[1] / "sprint_status.py"
+# Vendored copy of bmad-sprint-planning's sprint-status-template.yaml — skills
+# must not path into each other's directories (PATH-05). The repo-level
+# test/test-template-sync.js keeps this fixture identical to the source.
+TEMPLATE = Path(__file__).resolve().parent / "fixtures" / "sprint-status-template.yaml"
+
+FIXTURE = """\
+# Sprint Status Tracking
+# STATUS DEFINITIONS:
+#   backlog        - not yet started
+#   ready-for-dev  - ready to be implemented
+#   done           - completed
+generated: "01-01-2026 09:00"
+last_updated: "01-01-2026 09:00"
+project: "Demo Project"
+project_key: "DEMO"
+tracking_system: "file"
+story_location: "docs/stories"
+development_status:
+  epic-1: backlog
+  1-1-user-authentication: done
+  1-2-account-management: done
+  epic-1-retrospective: optional
+  epic-2: backlog
+  2-1-dashboard: backlog
+"""
+
+
+# Two epics' worth of items, because the flag's headline use is epic N's retro
+# closing epic N-1's items: nothing may scope a selector to --epic. The two
+# "Scripted item" entries share their action text and differ only by epic, so the
+# legacy epic+action selector has to discriminate on the epic to resolve at all.
+ACTION_FIXTURE = """\
+# Sprint Status Tracking
+# STATUS DEFINITIONS:
+#   open           - committed during a retrospective, not yet addressed
+generated: "01-01-2026 09:00"
+last_updated: "01-01-2026 09:00"
+development_status:
+  1-1-a: done
+  epic-1-retrospective: optional
+  2-1-b: done
+  epic-2-retrospective: optional
+
+# Action items committed during retrospectives
+action_items:
+  - id: "epic-1-retro-item-1-x"
+    epic: 1
+    action: "Scripted item"
+    owner: "Amelia"
+    status: "open"
+    ref: "docs/epic-1-retro.md"
+  - epic: 1
+    action: "Pre-existing item"
+    owner: "Charlie"
+    status: open
+  - id: "epic-2-retro-item-1-y"
+    epic: 2
+    action: "Scripted item"
+    owner: "Dana"
+    status: "in-progress"
+    ref: "docs/epic-2-retro.md"
+"""
+
+# Three spellings of the same scalar, to pin that a status write never re-styles
+# the line it lands on.
+STYLE_FIXTURE = """\
+last_updated: "01-01-2026 09:00"
+development_status:
+  1-1-a: done
+  epic-1-retrospective: optional
+action_items:
+  - id: "double"
+    epic: 1
+    action: "Double"
+    status: "open"
+  - id: "single"
+    epic: 1
+    action: "Single"
+    status: 'open'
+  - id: "plain"
+    epic: 1
+    action: "Plain"
+    status: open
+"""
+
+
+def _run(args):
+    cmd = ["uv", "run", str(SCRIPT), *args]
+    # LC_ALL=C keeps os.strerror text stable so error-string assertions do not
+    # depend on the developer's locale.
+    return subprocess.run(
+        cmd, capture_output=True, text=True, env={**os.environ, "LC_ALL": "C"}
+    )
+
+
+def _module():
+    """Import the script as a module, for the few properties that cannot be
+    triggered through the CLI (a failure after the temp file already exists)."""
+    spec = importlib.util.spec_from_file_location("sprint_status", SCRIPT)
+    mod = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(mod)
+    return mod
+
+
+def _write_fixture(tmp_path):
+    target = tmp_path / "sprint-status.yaml"
+    target.write_text(FIXTURE, encoding="utf-8")
+    return target
+
+
+def _write_action_fixture(tmp_path):
+    target = tmp_path / "sprint-status.yaml"
+    target.write_text(ACTION_FIXTURE, encoding="utf-8")
+    return target
+
+
+def _load(path):
+    yaml = YAML(typ="rt")
+    with open(path, "r", encoding="utf-8") as fh:
+        return yaml.load(fh)
+
+
+def _json(proc):
+    """Parse the JSON-only stdout contract, surfacing a crash instead of hiding
+    it behind a JSONDecodeError."""
+    assert proc.stdout, f"empty stdout; stderr was: {proc.stderr}"
+    assert "Traceback" not in proc.stderr, proc.stderr
+    return json.loads(proc.stdout)
+
+
+def test_detect_epic(tmp_path):
+    target = _write_fixture(tmp_path)
+    proc = _run(["detect-epic", "--file", str(target)])
+    assert proc.returncode == 0, proc.stderr
+    out = json.loads(proc.stdout)
+    assert out["epic"] == 1
+    assert out["story_count"] == 2
+    assert out["retro_key"] == "epic-1-retrospective"
+    assert out["retro_status"] == "optional"
+    assert set(out["done_stories"]) == {
+        "1-1-user-authentication",
+        "1-2-account-management",
+    }
+
+
+def test_detect_epic_rejects_typed_retrospective_status_as_json(tmp_path):
+    fixture = (
+        "development_status:\n"
+        "  1-1-a: done\n"
+        "  epic-1-retrospective: 2026-01-01\n"
+    )
+    target = tmp_path / "sprint-status.yaml"
+    target.write_text(fixture, encoding="utf-8")
+
+    proc = _run(["detect-epic", "--file", str(target)])
+
+    assert proc.returncode == 1
+    out = _json(proc)
+    assert out["ok"] is False
+    assert out["error"] == "epic-1-retrospective status must be a string or null"
+    assert "restored" not in out
+    assert target.read_text(encoding="utf-8") == fixture
+
+
+# --- pending_stories: the unfinished-epic gate --------------------------------
+
+
+def test_pending_stories_lists_the_selected_epics_unfinished_keys(tmp_path):
+    # The gate the skill branches on before Phase 1: an epic whose highest done
+    # story selected it, but which is not actually finished. Document order, so
+    # the listing the user confirms matches the file they can open.
+    fixture = (
+        "development_status:\n"
+        "  epic-2: backlog\n"
+        "  2-1-a: done\n"
+        "  2-2-b: backlog\n"
+        "  2-3-c: ready-for-dev\n"
+    )
+    target = tmp_path / "sprint-status.yaml"
+    target.write_text(fixture, encoding="utf-8")
+    proc = _run(["detect-epic", "--file", str(target)])
+    assert proc.returncode == 0, proc.stderr
+    out = _json(proc)
+    assert out["epic"] == 2
+    assert out["pending_stories"] == ["2-2-b", "2-3-c"]
+    # A non-story key sitting beside them never leaks in: STORY_RE gates entry.
+    assert "epic-2" not in out["pending_stories"]
+
+
+def test_pending_stories_is_empty_for_a_complete_epic(tmp_path):
+    fixture = (
+        "development_status:\n"
+        "  2-1-a: done\n"
+        "  2-2-b: done\n"
+        "  epic-2-retrospective: optional\n"
+    )
+    target = tmp_path / "sprint-status.yaml"
+    target.write_text(fixture, encoding="utf-8")
+    proc = _run(["detect-epic", "--file", str(target)])
+    assert proc.returncode == 0, proc.stderr
+    out = _json(proc)
+    assert out["epic"] == 2
+    assert out["pending_stories"] == []
+
+
+def test_pending_stories_ignores_other_epics(tmp_path):
+    # FIXTURE detects epic 1 while 2-1-dashboard sits at backlog. The key is
+    # scoped to the *selected* epic -- unlike done_stories, which spans the whole
+    # file -- so another epic's unfinished work must never block this retro.
+    target = _write_fixture(tmp_path)
+    proc = _run(["detect-epic", "--file", str(target)])
+    assert proc.returncode == 0, proc.stderr
+    out = _json(proc)
+    assert out["epic"] == 1
+    assert out["pending_stories"] == []
+    # done_stories keeps its whole-file scope, unchanged.
+    assert set(out["done_stories"]) == {
+        "1-1-user-authentication",
+        "1-2-account-management",
+    }
+
+
+def test_pending_stories_present_when_no_epic_is_detected(tmp_path):
+    # No done story anywhere: the shape stays uniform so a caller can read
+    # pending_stories without first branching on epic.
+    fixture = (
+        "development_status:\n"
+        "  1-1-a: backlog\n"
+        "  2-1-b: ready-for-dev\n"
+    )
+    target = tmp_path / "sprint-status.yaml"
+    target.write_text(fixture, encoding="utf-8")
+    proc = _run(["detect-epic", "--file", str(target)])
+    assert proc.returncode == 0, proc.stderr
+    out = _json(proc)
+    assert out["epic"] is None
+    assert out["story_count"] == 0
+    assert out["pending_stories"] == []
+
+
+def test_detect_epic_flag_aims_pending_stories_at_a_supplied_epic(tmp_path):
+    # Auto-detect would pick epic 2 (highest with a done story). --epic 1 aims
+    # the unfinished-epic gate at the orchestrator's explicit choice instead —
+    # the -H <epic> path that previously had no pending_stories at all.
+    fixture = (
+        "development_status:\n"
+        "  1-1-a: done\n"
+        "  1-2-b: backlog\n"
+        "  1-3-c: review\n"
+        "  2-1-a: done\n"
+        "  2-2-b: done\n"
+        "  epic-1-retrospective: optional\n"
+    )
+    target = tmp_path / "sprint-status.yaml"
+    target.write_text(fixture, encoding="utf-8")
+    proc = _run(["detect-epic", "--file", str(target), "--epic", "1"])
+    assert proc.returncode == 0, proc.stderr
+    out = _json(proc)
+    assert out["epic"] == 1
+    assert out["retro_key"] == "epic-1-retrospective"
+    assert out["retro_status"] == "optional"
+    assert out["pending_stories"] == ["1-2-b", "1-3-c"]
+    # done_stories keeps its whole-file scope.
+    assert set(out["done_stories"]) == {"1-1-a", "2-1-a", "2-2-b"}
+
+
+def test_detect_epic_flag_lists_pending_when_no_story_is_done(tmp_path):
+    # Without --epic, no done story means epic is null. With --epic, an
+    # unfinished epic that never landed a done story is still addressable —
+    # every story key of that epic is pending.
+    fixture = (
+        "development_status:\n"
+        "  3-1-a: backlog\n"
+        "  3-2-b: ready-for-dev\n"
+    )
+    target = tmp_path / "sprint-status.yaml"
+    target.write_text(fixture, encoding="utf-8")
+    proc = _run(["detect-epic", "--file", str(target), "--epic", "3"])
+    assert proc.returncode == 0, proc.stderr
+    out = _json(proc)
+    assert out["epic"] == 3
+    assert out["pending_stories"] == ["3-1-a", "3-2-b"]
+    assert out["retro_key"] == "epic-3-retrospective"
+    assert out["retro_status"] is None
+
+
+def test_detect_epic_flag_empty_pending_for_a_complete_supplied_epic(tmp_path):
+    fixture = (
+        "development_status:\n"
+        "  1-1-a: done\n"
+        "  1-2-b: done\n"
+        "  2-1-a: backlog\n"
+    )
+    target = tmp_path / "sprint-status.yaml"
+    target.write_text(fixture, encoding="utf-8")
+    proc = _run(["detect-epic", "--file", str(target), "--epic", "1"])
+    assert proc.returncode == 0, proc.stderr
+    out = _json(proc)
+    assert out["epic"] == 1
+    assert out["pending_stories"] == []
+
+
+def test_detect_epic_flag_zero_story_count_marks_a_nonexistent_epic(tmp_path):
+    # --epic 9 against a file that has no epic-9 stories: pending_stories is
+    # empty exactly as it is for a finished epic, so story_count is the only
+    # signal separating "complete" from "typo'd". The gate reads 0 as suspect,
+    # never as done.
+    fixture = (
+        "development_status:\n"
+        "  1-1-a: done\n"
+        "  1-2-b: done\n"
+    )
+    target = tmp_path / "sprint-status.yaml"
+    target.write_text(fixture, encoding="utf-8")
+    proc = _run(["detect-epic", "--file", str(target), "--epic", "9"])
+    assert proc.returncode == 0, proc.stderr
+    out = _json(proc)
+    assert out["epic"] == 9
+    assert out["story_count"] == 0
+    assert out["pending_stories"] == []
+    assert out["retro_status"] is None
+    # The finished epic it could be confused with reports its real count.
+    proc = _run(["detect-epic", "--file", str(target), "--epic", "1"])
+    out = _json(proc)
+    assert out["story_count"] == 2
+    assert out["pending_stories"] == []
+
+
+def test_detect_epic_flag_rejects_non_positive_epic(tmp_path):
+    target = _write_fixture(tmp_path)
+    for bad in ("0", "-3"):
+        proc = _run(["detect-epic", "--file", str(target), "--epic", bad])
+        assert proc.returncode == 1, proc.stderr
+        out = _json(proc)
+        assert out["ok"] is False
+        assert "epic" in out["error"]
+        assert "restored" not in out
+
+
+def test_update_rejects_non_positive_epic(tmp_path):
+    target = _write_fixture(tmp_path)
+    for bad in ("0", "-3"):
+        proc = _run(["update", "--file", str(target), "--epic", bad])
+        assert proc.returncode == 1, proc.stderr
+        assert "positive integer" in _json(proc)["error"]
+        assert target.read_text(encoding="utf-8") == FIXTURE
+
+
+# --- The JSON-only contract covers the help paths ----------------------------
+
+
+@pytest.mark.parametrize(
+    "args",
+    [["-h"], ["--help"], ["detect-epic", "-h"], ["detect-epic", "--help"]],
+    ids=["top-short", "top-long", "sub-short", "sub-long"],
+)
+def test_help_flags_emit_json_not_usage(args):
+    # argparse's built-in help action bypasses error() -- it prints usage text
+    # to stdout and exits 0, which is exactly the contract this script sells.
+    # add_help=False turns -h into an ordinary unrecognized argument instead.
+    proc = _run(args)
+    # Exit 2 specifically: the module docstring reserves 2 for argument errors
+    # and 1 for I/O failures, and retro-document.md teaches callers to tell the
+    # two apart, so collapsing them must fail here.
+    assert proc.returncode == 2
+    assert "usage:" not in proc.stdout
+    out = _json(proc)
+    assert out["ok"] is False
+    assert out["error"]
+    # An argparse rejection speaks for no file, so it carries no "restored" --
+    # the same rule test_only_the_write_path_reports_restored pins for exit 1.
+    assert "restored" not in out
+
+
+@pytest.mark.parametrize("flag", ["-h", "--help"])
+def test_update_help_flag_emits_json_not_usage(tmp_path, flag):
+    # The update subparser too, driven with its required arguments present so
+    # nothing but the help flag itself can be what argparse objects to.
+    target = _write_fixture(tmp_path)
+    proc = _run(["update", "--file", str(target), "--epic", "1", flag])
+    assert proc.returncode == 2
+    assert "usage:" not in proc.stdout
+    out = _json(proc)
+    assert out["ok"] is False
+    assert flag in out["error"]
+    assert "restored" not in out
+    # A rejected invocation must not have written anything.
+    assert target.read_text(encoding="utf-8") == FIXTURE
+
+
+def test_update_sets_retro_and_appends_action(tmp_path):
+    target = _write_fixture(tmp_path)
+    payload = '[{"action":"Fix #42: colons: and # hashes","owner":"Amelia"}]'
+    proc = _run(
+        [
+            "update",
+            "--file",
+            str(target),
+            "--epic",
+            "1",
+            "--set-retro-done",
+            "--add-action",
+            payload,
+        ]
+    )
+    assert proc.returncode == 0, proc.stderr
+    out = json.loads(proc.stdout)
+    assert out["ok"] is True
+    assert out["retro_key_found"] is True
+    assert out["retro_status_after"] == "done"
+    assert out["action_items_added"] == 1
+
+    # File must still parse cleanly (punctuation did not corrupt it).
+    data = _load(target)
+    assert data is not None
+
+    # STATUS DEFINITIONS comment survived.
+    raw = target.read_text(encoding="utf-8")
+    assert "STATUS DEFINITIONS" in raw
+
+    # Retro status flipped to done.
+    assert data["development_status"]["epic-1-retrospective"] == "done"
+
+    # The action value round-trips with literal '#' and ':' intact.
+    action = data["action_items"][0]
+    assert action["action"] == "Fix #42: colons: and # hashes"
+    assert action["owner"] == "Amelia"
+    assert action["epic"] == 1
+    assert action["status"] == "open"
+
+
+def test_update_rejects_typed_retrospective_status_before_writing(tmp_path):
+    fixture = (
+        "last_updated: 01-01-2026 09:00\n"
+        "development_status:\n"
+        "  1-1-a: done\n"
+        "  epic-1-retrospective: 2026-01-01\n"
+    )
+    target = tmp_path / "sprint-status.yaml"
+    target.write_text(fixture, encoding="utf-8")
+
+    proc = _run(
+        [
+            "update",
+            "--file",
+            str(target),
+            "--epic",
+            "1",
+            "--set-retro-done",
+            "--add-action",
+            '[{"action":"Must not be appended","owner":"Amelia"}]',
+        ]
+    )
+
+    assert proc.returncode == 1
+    out = _json(proc)
+    assert out["ok"] is False
+    assert out["restored"] is True
+    assert out["error"] == "epic-1-retrospective status must be a string or null"
+    assert target.read_text(encoding="utf-8") == fixture
+
+
+def test_detect_epic_matches_split_story_keys(tmp_path):
+    # A split-story key like 2-6a-... is first-class in BMAD (an oversized story
+    # split into 2-6a / 2-6b) and must not be invisible to detection — otherwise
+    # an epic whose only done stories are splits is silently skipped.
+    fixture = (
+        "development_status:\n"
+        "  1-1-first: done\n"
+        "  2-6a-split-auth: done\n"
+        "  epic-2-retrospective: optional\n"
+    )
+    target = tmp_path / "sprint-status.yaml"
+    target.write_text(fixture, encoding="utf-8")
+    proc = _run(["detect-epic", "--file", str(target)])
+    assert proc.returncode == 0, proc.stderr
+    out = json.loads(proc.stdout)
+    assert out["epic"] == 2
+    assert "2-6a-split-auth" in out["done_stories"]
+    assert out["retro_key"] == "epic-2-retrospective"
+
+
+def test_update_rejects_non_list_action_items(tmp_path):
+    # A hand-corrupted action_items must fail on the JSON contract, not crash.
+    fixture = (
+        "development_status:\n"
+        "  1-1-a: done\n"
+        "  epic-1-retrospective: optional\n"
+        'action_items: "oops-not-a-list"\n'
+    )
+    target = tmp_path / "sprint-status.yaml"
+    target.write_text(fixture, encoding="utf-8")
+    proc = _run(
+        ["update", "--file", str(target), "--epic", "1",
+         "--add-action", '[{"action":"x","owner":"y"}]']
+    )
+    assert proc.returncode == 1
+    out = json.loads(proc.stdout)  # must be JSON, not a traceback
+    assert out["ok"] is False
+    assert "action_items" in out["error"]
+
+
+def test_appended_items_carry_id_and_ref(tmp_path):
+    target = _write_fixture(tmp_path)
+    ref = "docs/stories/epic-1-retro-2026-07-21.md"
+    proc = _run(
+        ["update", "--file", str(target), "--epic", "1", "--set-retro-done",
+         "--add-action", '[{"action":"Fix the seam","owner":"Amelia"}]',
+         "--ref", ref, "--verdict", "accepted-with-open-items"]
+    )
+    assert proc.returncode == 0, proc.stderr
+    out = json.loads(proc.stdout)
+    assert out["verdict"] == "accepted-with-open-items"  # echoed, not written to a key
+
+    item = _load(target)["action_items"][0]
+    assert item["id"].startswith("epic-1-retro-item-1-")
+    assert item["ref"] == ref
+    # The retro key value stays "done" — verdict is not encoded into it.
+    assert _load(target)["development_status"]["epic-1-retrospective"] == "done"
+
+
+def test_free_spelled_verdict_is_rejected_before_the_file_is_touched(tmp_path):
+    # The SKILL's prose verdict ("accepted with open items") and the frontmatter
+    # token (accepted-with-open-items) used to be two spellings of one value; an
+    # orchestrator branching on the echo would fall through both. Only the
+    # frontmatter vocabulary passes; anything else fails with the file intact.
+    target = _write_fixture(tmp_path)
+    for bad in ("accepted with open items", "ship it", "ACCEPTED"):
+        proc = _run(
+            ["update", "--file", str(target), "--epic", "1", "--set-retro-done",
+             "--verdict", bad]
+        )
+        assert proc.returncode == 1, f"accepted {bad!r}"
+        out = _json(proc)
+        assert out["ok"] is False and "--verdict" in out["error"]
+        assert out["restored"] is True
+    assert target.read_text(encoding="utf-8") == FIXTURE
+
+
+def test_explicit_item_id_is_preserved(tmp_path):
+    target = _write_fixture(tmp_path)
+    proc = _run(
+        ["update", "--file", str(target), "--epic", "1",
+         "--add-action", '[{"action":"a","owner":"o","id":"custom-id-7"}]']
+    )
+    assert proc.returncode == 0, proc.stderr
+    assert _load(target)["action_items"][0]["id"] == "custom-id-7"
+
+
+@pytest.mark.skipif(
+    hasattr(os, "geteuid") and os.geteuid() == 0,
+    reason="root bypasses file permission bits",
+)
+def test_write_failure_reports_restore_status(tmp_path):
+    # If the write cannot happen, the caller must be told whether the original
+    # was restored — a silent failure defeats the script's core guarantee.
+    #
+    # The write is atomic (temp file + os.replace), and os.replace needs write
+    # permission on the *directory*, not on the target — a read-only target is
+    # now replaceable. Making the containing directory read-only is what blocks
+    # the write: mkstemp fails, while the restore write to the still-writable
+    # target succeeds.
+    holder = tmp_path / "holder"
+    holder.mkdir()
+    target = _write_fixture(holder)
+    os.chmod(holder, 0o555)
+    try:
+        proc = _run(
+            ["update", "--file", str(target), "--epic", "1", "--set-retro-done"]
+        )
+    finally:
+        os.chmod(holder, 0o755)
+    assert proc.returncode == 1
+    out = _json(proc)
+    assert out["ok"] is False
+    assert out["restored"] is True
+    # The file was never touched: the temp file could not even be created.
+    assert target.read_text(encoding="utf-8") == FIXTURE
+    assert [p.name for p in holder.iterdir()] == ["sprint-status.yaml"]
+
+
+def test_punctuation_does_not_corrupt_file(tmp_path):
+    # Explicit re-parse guarantee for YAML-breaking punctuation.
+    target = _write_fixture(tmp_path)
+    payload = '[{"action":"weird: value # with: hashes","owner":"Bob # Smith"}]'
+    proc = _run(
+        [
+            "update",
+            "--file",
+            str(target),
+            "--epic",
+            "1",
+            "--add-action",
+            payload,
+        ]
+    )
+    assert proc.returncode == 0, proc.stderr
+    # Re-parse must succeed and preserve the literal punctuation.
+    data = _load(target)
+    assert data["action_items"][0]["action"] == "weird: value # with: hashes"
+    assert data["action_items"][0]["owner"] == "Bob # Smith"
+
+
+# --- Formatting fidelity -----------------------------------------------------
+
+
+def test_template_round_trip_changes_only_last_updated(tmp_path):
+    # The repo's own sprint-status template is the shape every generated file
+    # inherits: 2-space sequence indent and a mid-file comment above
+    # action_items. An update must touch nothing but last_updated — a re-indent
+    # of a pre-existing, untouched entry defeats the preservation guarantee that
+    # motivates "do not hand-edit this file".
+    source = TEMPLATE.read_text(encoding="utf-8")
+    target = tmp_path / "sprint-status.yaml"
+    target.write_text(source, encoding="utf-8")
+
+    proc = _run(
+        ["update", "--file", str(target), "--epic", "1", "--date", "01-01-2026 09:00"]
+    )
+    assert proc.returncode == 0, proc.stderr
+    assert _json(proc)["ok"] is True
+
+    before = source.splitlines()
+    after = target.read_text(encoding="utf-8").splitlines()
+    assert len(before) == len(after)
+    changed = [(b, a) for b, a in zip(before, after) if b != a]
+    assert len(changed) == 1, changed
+    assert changed[0][1] == "last_updated: 01-01-2026 09:00"
+    # The pre-existing action item keeps its 2-space sequence indent.
+    assert "  - epic: 1" in after
+
+
+def test_mid_file_comment_survives_update(tmp_path):
+    fixture = (
+        "# header\n"
+        "development_status:\n"
+        "  1-1-a: done\n"
+        "  epic-1-retrospective: optional\n"
+        "\n"
+        "# Action items committed during retrospectives\n"
+        "action_items:\n"
+        "  - epic: 1\n"
+        '    action: "Pre-existing item"\n'
+        '    owner: "Charlie"\n'
+        "    status: open\n"
+    )
+    target = tmp_path / "sprint-status.yaml"
+    target.write_text(fixture, encoding="utf-8")
+    proc = _run(
+        ["update", "--file", str(target), "--epic", "1", "--set-retro-done",
+         "--add-action", '[{"action":"New item","owner":"Amelia"}]']
+    )
+    assert proc.returncode == 0, proc.stderr
+    raw = target.read_text(encoding="utf-8")
+    assert "# Action items committed during retrospectives" in raw
+    assert "# header" in raw
+    assert '    action: "Pre-existing item"' in raw
+
+
+def test_legacy_offset_zero_file_is_canonicalized(tmp_path):
+    # Files the previous version of this script wrote carry action_items at
+    # column 0. The indent pin re-indents them to the template's shape on the
+    # next write. That is a deliberate one-time canonicalization, not a silent
+    # failure: the update still succeeds and no comment is lost.
+    fixture = (
+        "# header\n"
+        "development_status:\n"
+        "  1-1-a: done\n"
+        "  epic-1-retrospective: optional\n"
+        "action_items:\n"
+        '- id: "legacy"\n'
+        "  epic: 1\n"
+        '  action: "written by the old code"\n'
+        "  status: open\n"
+    )
+    target = tmp_path / "sprint-status.yaml"
+    target.write_text(fixture, encoding="utf-8")
+    proc = _run(["update", "--file", str(target), "--epic", "1", "--set-retro-done"])
+    assert proc.returncode == 0, proc.stderr
+    raw = target.read_text(encoding="utf-8")
+    assert '  - id: "legacy"' in raw
+    assert '    action: "written by the old code"' in raw
+    assert "# header" in raw
+
+
+def test_lost_comment_fails_with_restore(tmp_path):
+    # A standalone comment inside a flow collection is genuinely dropped by the
+    # round-trip. The leading-block check never saw it; the full multiset does,
+    # and the original bytes must come back.
+    fixture = (
+        "# header\n"
+        "development_status:\n"
+        "  1-1-a: done\n"
+        "  epic-1-retrospective: optional\n"
+        "tags: [\n"
+        "  # a standalone comment the round-trip drops\n"
+        '  "alpha",\n'
+        '  "beta",\n'
+        "]\n"
+    )
+    target = tmp_path / "sprint-status.yaml"
+    target.write_text(fixture, encoding="utf-8")
+    proc = _run(
+        ["update", "--file", str(target), "--epic", "1", "--set-retro-done"]
+    )
+    assert proc.returncode == 1
+    out = _json(proc)
+    assert out["ok"] is False
+    assert out["restored"] is True
+    assert "comment line lost" in out["error"]
+    assert "a standalone comment the round-trip drops" in out["error"]
+    assert target.read_text(encoding="utf-8") == fixture
+
+
+# --- Malformed input stays on the JSON contract ------------------------------
+
+
+@pytest.mark.parametrize("command", ["detect-epic", "update"])
+def test_non_mapping_root_is_json_error(tmp_path, command):
+    target = tmp_path / "sprint-status.yaml"
+    target.write_text("- a\n- b\n", encoding="utf-8")
+    args = ["--file", str(target)] + (["--epic", "1"] if command == "update" else [])
+    proc = _run([command, *args])
+    assert proc.returncode == 1
+    out = _json(proc)
+    assert out["ok"] is False
+    assert "root document is not a mapping" in out["error"]
+    assert target.read_text(encoding="utf-8") == "- a\n- b\n"
+
+
+@pytest.mark.parametrize("command", ["detect-epic", "update"])
+@pytest.mark.parametrize(
+    "body",
+    ['development_status: "not-a-mapping"\n', "development_status:\n  - a\n  - b\n"],
+    ids=["scalar", "list"],
+)
+def test_non_mapping_development_status_is_json_error(tmp_path, command, body):
+    target = tmp_path / "sprint-status.yaml"
+    target.write_text(body, encoding="utf-8")
+    args = ["--file", str(target)] + (["--epic", "1"] if command == "update" else [])
+    proc = _run([command, *args])
+    # update used to report ok:true here while silently doing nothing.
+    assert proc.returncode == 1
+    out = _json(proc)
+    assert out["ok"] is False
+    assert "development_status is not a mapping" in out["error"]
+
+
+@pytest.mark.parametrize("command", ["detect-epic", "update"])
+def test_directory_target_is_json_error(tmp_path, command):
+    target = tmp_path / "a-directory"
+    target.mkdir()
+    args = ["--file", str(target)] + (["--epic", "1"] if command == "update" else [])
+    proc = _run([command, *args])
+    assert proc.returncode == 1
+    out = _json(proc)
+    assert out["ok"] is False
+    assert out["error"]
+
+
+@pytest.mark.skipif(
+    hasattr(os, "geteuid") and os.geteuid() == 0,
+    reason="root bypasses file permission bits",
+)
+@pytest.mark.parametrize("command", ["detect-epic", "update"])
+def test_unreadable_target_is_json_error(tmp_path, command):
+    # The other half of the OSError widening: PermissionError, not just
+    # IsADirectoryError, has to stay on the JSON contract.
+    target = _write_fixture(tmp_path)
+    os.chmod(target, 0o000)
+    args = ["--file", str(target)] + (["--epic", "1"] if command == "update" else [])
+    try:
+        proc = _run([command, *args])
+    finally:
+        os.chmod(target, 0o644)
+    assert proc.returncode == 1
+    out = _json(proc)
+    assert out["ok"] is False
+    assert "denied" in out["error"].lower()
+
+
+@pytest.mark.parametrize("command", ["detect-epic", "update"])
+def test_invalid_utf8_is_json_error(tmp_path, command):
+    target = tmp_path / "sprint-status.yaml"
+    target.write_bytes(b"development_status:\n  1-1-a: d\xffone\n")
+    args = ["--file", str(target)] + (["--epic", "1"] if command == "update" else [])
+    proc = _run([command, *args])
+    assert proc.returncode == 1
+    out = _json(proc)
+    assert out["ok"] is False
+    assert "utf-8" in out["error"].lower()
+
+
+# --- Atomic write ------------------------------------------------------------
+
+
+def test_atomic_write_failure_leaves_target_byte_identical(tmp_path, monkeypatch):
+    # The failure the atomic write exists for: something goes wrong after the
+    # temp file has been written. Nothing may reach the target and no temp file
+    # may survive. No CLI path reaches here -- a read-only directory fails at
+    # mkstemp instead -- so this drives the helper directly.
+    mod = _module()
+    target = _write_fixture(tmp_path)
+
+    def boom(*args, **kwargs):
+        raise OSError(28, "No space left on device")
+
+    monkeypatch.setattr(mod.os, "replace", boom)
+    with pytest.raises(OSError):
+        mod._atomic_write(str(target), b"replacement bytes\n", 0o644)
+    assert target.read_text(encoding="utf-8") == FIXTURE
+    assert [p.name for p in tmp_path.iterdir()] == ["sprint-status.yaml"]
+
+
+def test_dir_fsync_failure_after_rename_is_not_a_write_failure(tmp_path, monkeypatch):
+    # Once os.replace has returned, the new bytes ARE the file. The directory
+    # fsync that follows is durability polish; if it raised, cmd_update would
+    # emit "restored": true about a write that in fact landed — the one lie the
+    # restored contract exists to prevent. Deny opening the directory (the only
+    # thing _atomic_write opens by path after the rename) and require success.
+    mod = _module()
+    target = _write_fixture(tmp_path)
+    directory = os.path.dirname(os.path.realpath(str(target)))
+    real_open = os.open
+
+    def deny_directory_open(p, *args, **kwargs):
+        if p == directory:
+            raise OSError(5, "Input/output error")
+        return real_open(p, *args, **kwargs)
+
+    monkeypatch.setattr(mod.os, "open", deny_directory_open)
+    mod._atomic_write(str(target), b"replacement bytes\n", 0o644)
+    assert target.read_bytes() == b"replacement bytes\n"
+    assert [p.name for p in tmp_path.iterdir()] == ["sprint-status.yaml"]
+
+
+def test_restore_is_atomic(tmp_path, monkeypatch):
+    # _restore is the rollback the reference sells as the safety net. A
+    # truncating rewrite that dies halfway would destroy the very bytes it is
+    # putting back, which is how a full disk used to corrupt the file.
+    mod = _module()
+    target = tmp_path / "sprint-status.yaml"
+    target.write_text("damaged\n", encoding="utf-8")
+
+    def boom(*args, **kwargs):
+        raise OSError(28, "No space left on device")
+
+    monkeypatch.setattr(mod.os, "replace", boom)
+    assert mod._restore(str(target), FIXTURE.encode("utf-8"), 0o644) is False
+    # It reported failure honestly and left the file no worse than it found it.
+    assert target.read_text(encoding="utf-8") == "damaged\n"
+    assert [p.name for p in tmp_path.iterdir()] == ["sprint-status.yaml"]
+
+
+def test_symlinked_target_is_written_through(tmp_path):
+    # os.replace onto a symlink would detach the link and leave the real file
+    # stale while reporting ok:true.
+    real = tmp_path / "real-sprint-status.yaml"
+    real.write_text(FIXTURE, encoding="utf-8")
+    link = tmp_path / "sprint-status.yaml"
+    link.symlink_to(real)
+    proc = _run(["update", "--file", str(link), "--epic", "1", "--set-retro-done"])
+    assert proc.returncode == 0, proc.stderr
+    assert link.is_symlink(), "the symlink was replaced by a regular file"
+    assert _load(real)["development_status"]["epic-1-retrospective"] == "done"
+
+
+def test_atomic_write_preserves_mode_and_leaves_no_temp_file(tmp_path):
+    # mkstemp creates 0600; without carrying the target's mode over, every
+    # update would silently narrow the file.
+    holder = tmp_path / "holder"
+    holder.mkdir()
+    target = _write_fixture(holder)
+    os.chmod(target, 0o640)
+    proc = _run(["update", "--file", str(target), "--epic", "1", "--set-retro-done"])
+    assert proc.returncode == 0, proc.stderr
+    assert stat.S_IMODE(target.stat().st_mode) == 0o640
+    assert [p.name for p in holder.iterdir()] == ["sprint-status.yaml"]
+
+
+# --- Result-JSON precision ---------------------------------------------------
+
+
+def test_retro_key_found_is_null_without_the_flag(tmp_path):
+    # No development_status key at all: the update must not conjure one, and
+    # retro_key_found must say "not asked" rather than "absent".
+    fixture = 'project: "Demo"\nlast_updated: "01-01-2026 09:00"\n'
+    target = tmp_path / "sprint-status.yaml"
+    target.write_text(fixture, encoding="utf-8")
+    proc = _run(["update", "--file", str(target), "--epic", "1"])
+    assert proc.returncode == 0, proc.stderr
+    out = _json(proc)
+    assert out["ok"] is True
+    assert out["retro_key_found"] is None
+    assert "development_status" not in target.read_text(encoding="utf-8")
+
+
+def test_retro_key_found_is_false_when_the_key_is_absent(tmp_path):
+    target = _write_fixture(tmp_path)
+    proc = _run(["update", "--file", str(target), "--epic", "2", "--set-retro-done"])
+    assert proc.returncode == 0, proc.stderr
+    out = _json(proc)
+    assert out["ok"] is True
+    assert out["retro_key_found"] is False
+    # Nothing was written into the mapping.
+    assert "epic-2-retrospective" not in _load(target)["development_status"]
+
+
+@pytest.mark.parametrize("command", ["detect-epic", "update"])
+def test_only_the_write_path_reports_restored(tmp_path, command):
+    # "restored" speaks to the state of a file the command may have written.
+    # detect-epic never writes, so inventing the key there would mislead callers
+    # that branch on it.
+    target = tmp_path / "sprint-status.yaml"
+    target.write_text("- a\n- b\n", encoding="utf-8")
+    args = ["--file", str(target)] + (["--epic", "1"] if command == "update" else [])
+    out = _json(_run([command, *args]))
+    assert out["ok"] is False
+    assert ("restored" in out) is (command == "update")
+
+
+def test_pre_write_failure_reports_restored(tmp_path):
+    # retro-document.md teaches callers that ok:false carries restored:true;
+    # a failure before the write must not read as "the file may be incomplete".
+    target = _write_fixture(tmp_path)
+    proc = _run(
+        ["update", "--file", str(target), "--epic", "1", "--add-action", "{not json"]
+    )
+    assert proc.returncode == 1
+    out = _json(proc)
+    assert out["ok"] is False
+    assert out["restored"] is True
+    assert target.read_text(encoding="utf-8") == FIXTURE
+
+
+# --- Action-item validation and identity -------------------------------------
+
+
+def test_non_latin_action_keeps_its_text_in_the_id(tmp_path):
+    target = _write_fixture(tmp_path)
+    payload = json.dumps(
+        [{"action": "Улучшить обработку ошибок", "owner": "Amelia"}],
+        ensure_ascii=False,
+    )
+    proc = _run(["update", "--file", str(target), "--epic", "1", "--add-action", payload])
+    assert proc.returncode == 0, proc.stderr
+    item_id = _load(target)["action_items"][0]["id"]
+    assert item_id == "epic-1-retro-item-1-улучшить-обработку-ошибок"
+
+
+def test_unsluggable_action_falls_back_to_a_hash(tmp_path):
+    target = _write_fixture(tmp_path)
+    payload = json.dumps([{"action": "!!! 🎉", "owner": "Amelia"}], ensure_ascii=False)
+    proc = _run(["update", "--file", str(target), "--epic", "1", "--add-action", payload])
+    assert proc.returncode == 0, proc.stderr
+    item_id = _load(target)["action_items"][0]["id"]
+    assert not item_id.endswith("-item")
+    assert re.fullmatch(r"epic-1-retro-item-1-[0-9a-f]{8}", item_id), item_id
+
+
+def test_empty_action_is_rejected(tmp_path):
+    target = _write_fixture(tmp_path)
+    proc = _run(
+        ["update", "--file", str(target), "--epic", "1",
+         "--add-action", '[{"action":"   ","owner":"x"}]']
+    )
+    assert proc.returncode == 1
+    out = _json(proc)
+    assert out["ok"] is False
+    assert out["restored"] is True
+    assert "action" in out["error"]
+    assert target.read_text(encoding="utf-8") == FIXTURE
+
+
+def test_non_string_action_is_rejected(tmp_path):
+    # A JSON null would otherwise be str()'d into a literal "None" and written
+    # as a real action item, which the new emptiness check alone lets through.
+    target = _write_fixture(tmp_path)
+    proc = _run(
+        ["update", "--file", str(target), "--epic", "1",
+         "--add-action", '[{"action":null,"owner":"x"}]']
+    )
+    assert proc.returncode == 1
+    out = _json(proc)
+    assert out["ok"] is False
+    assert out["restored"] is True
+    assert target.read_text(encoding="utf-8") == FIXTURE
+
+
+def test_date_is_normalized_to_the_canonical_format(tmp_path):
+    # strptime accepts unpadded spellings; writing those through would defeat
+    # the point of validating the format.
+    target = _write_fixture(tmp_path)
+    proc = _run(
+        ["update", "--file", str(target), "--epic", "1", "--date", "1-2-2026 9:05"]
+    )
+    assert proc.returncode == 0, proc.stderr
+    assert _json(proc)["last_updated"] == "01-02-2026 09:05"
+    assert _load(target)["last_updated"] == "01-02-2026 09:05"
+
+
+def test_malformed_date_is_rejected(tmp_path):
+    target = _write_fixture(tmp_path)
+    proc = _run(
+        ["update", "--file", str(target), "--epic", "1", "--date", "not-a-date"]
+    )
+    assert proc.returncode == 1
+    out = _json(proc)
+    assert out["ok"] is False
+    assert out["restored"] is True
+    assert "--date" in out["error"]
+    assert target.read_text(encoding="utf-8") == FIXTURE
+
+
+# --- Action-item status transitions ------------------------------------------
+
+
+def test_set_action_status_applies_both_selector_forms(tmp_path):
+    # The whole point of the flag: an item written by this script (selected by
+    # id) and a legacy item that predates ids (selected by epic + exact action
+    # text) both move off "open" in a single call.
+    target = _write_action_fixture(tmp_path)
+    payload = json.dumps(
+        [
+            {"id": "epic-1-retro-item-1-x", "status": "done"},
+            {"epic": 1, "action": "Pre-existing item", "status": "in-progress"},
+        ]
+    )
+    proc = _run(
+        ["update", "--file", str(target), "--epic", "1", "--set-action-status", payload]
+    )
+    assert proc.returncode == 0, proc.stderr
+    out = _json(proc)
+    assert out["ok"] is True
+    assert out["action_items_updated"] == 2
+    assert out["action_items_added"] == 0
+
+    items = _load(target)["action_items"]
+    assert items[0]["status"] == "done"
+    assert items[1]["status"] == "in-progress"
+    # Every other key of both items survived untouched, in place.
+    assert items[0]["id"] == "epic-1-retro-item-1-x"
+    assert items[0]["epic"] == 1
+    assert items[0]["action"] == "Scripted item"
+    assert items[0]["owner"] == "Amelia"
+    assert items[0]["ref"] == "docs/epic-1-retro.md"
+    assert "id" not in items[1]
+    assert items[1]["epic"] == 1
+    assert items[1]["action"] == "Pre-existing item"
+    assert items[1]["owner"] == "Charlie"
+    # The epic-2 item shares its action text with items[0]; the epic-1 selector
+    # must not have touched it.
+    assert items[2]["status"] == "in-progress"
+    assert items[2]["id"] == "epic-2-retro-item-1-y"
+    assert len(items) == 3
+
+
+def test_set_action_status_changes_exactly_one_line(tmp_path):
+    # The status write is surgical: it must not re-style neighbouring lines, and
+    # an item whose status was quoted keeps its quoting. last_updated is rewritten
+    # with the same text it already held, so the whole file differs by one line.
+    target = _write_action_fixture(tmp_path)
+    proc = _run(
+        ["update", "--file", str(target), "--epic", "1", "--date", "01-01-2026 09:00",
+         "--set-action-status", '[{"id":"epic-1-retro-item-1-x","status":"done"}]']
+    )
+    assert proc.returncode == 0, proc.stderr
+
+    before = ACTION_FIXTURE.splitlines()
+    after = target.read_text(encoding="utf-8").splitlines()
+    assert len(before) == len(after)
+    changed = [(b, a) for b, a in zip(before, after) if b != a]
+    assert changed == [('    status: "open"', '    status: "done"')], changed
+
+
+def test_set_action_status_composes_with_retro_done_and_add_action(tmp_path):
+    target = _write_action_fixture(tmp_path)
+    proc = _run(
+        ["update", "--file", str(target), "--epic", "1", "--set-retro-done",
+         "--add-action", '[{"action":"Brand new item","owner":"Amelia"}]',
+         "--set-action-status",
+         '[{"epic":1,"action":"Pre-existing item","status":"done"}]']
+    )
+    assert proc.returncode == 0, proc.stderr
+    out = _json(proc)
+    assert out["ok"] is True
+    assert out["retro_status_after"] == "done"
+    assert out["action_items_added"] == 1
+    assert out["action_items_updated"] == 1
+
+    data = _load(target)
+    assert data["development_status"]["epic-1-retrospective"] == "done"
+    items = data["action_items"]
+    assert len(items) == 4
+    assert items[1]["status"] == "done"  # the targeted pre-existing item
+    assert items[3]["action"] == "Brand new item"
+    assert items[3]["status"] == "open"  # the appended item is always open
+
+
+def test_set_action_status_cannot_target_an_item_added_in_the_same_run(tmp_path):
+    # Selectors resolve against action_items as loaded, so the append cannot be
+    # observed by the same invocation. Silently succeeding here would make the
+    # flag a back door for writing a non-open status onto a brand-new item.
+    target = _write_action_fixture(tmp_path)
+    proc = _run(
+        ["update", "--file", str(target), "--epic", "1",
+         "--add-action", '[{"action":"Brand new","owner":"A","id":"brand-new"}]',
+         "--set-action-status", '[{"id":"brand-new","status":"done"}]']
+    )
+    assert proc.returncode == 1
+    out = _json(proc)
+    assert out["ok"] is False
+    assert out["restored"] is True
+    assert "no action item matches" in out["error"]
+    assert target.read_text(encoding="utf-8") == ACTION_FIXTURE
+
+
+def test_set_action_status_rejects_unknown_id(tmp_path):
+    target = _write_action_fixture(tmp_path)
+    proc = _run(
+        ["update", "--file", str(target), "--epic", "1",
+         "--set-action-status", '[{"id":"not-in-the-file","status":"done"}]']
+    )
+    assert proc.returncode == 1
+    out = _json(proc)
+    assert out["ok"] is False
+    assert out["restored"] is True
+    assert "not-in-the-file" in out["error"]
+    assert target.read_text(encoding="utf-8") == ACTION_FIXTURE
+
+
+def test_set_action_status_rejects_selector_when_action_items_is_absent(tmp_path):
+    # No action_items key at all must read as "no match", not as a crash.
+    target = _write_fixture(tmp_path)
+    proc = _run(
+        ["update", "--file", str(target), "--epic", "1",
+         "--set-action-status", '[{"id":"anything","status":"done"}]']
+    )
+    assert proc.returncode == 1
+    out = _json(proc)
+    assert out["ok"] is False
+    assert out["restored"] is True
+    assert "no action item matches" in out["error"]
+    assert target.read_text(encoding="utf-8") == FIXTURE
+
+
+def test_set_action_status_rejects_ambiguous_selector(tmp_path):
+    # Two legacy items with identical epic + action text: guessing between them
+    # would write the wrong row half the time.
+    fixture = (
+        "development_status:\n"
+        "  1-1-a: done\n"
+        "  epic-1-retrospective: optional\n"
+        "action_items:\n"
+        "  - epic: 1\n"
+        '    action: "Same text"\n'
+        '    owner: "Charlie"\n'
+        "    status: open\n"
+        "  - epic: 1\n"
+        '    action: "Same text"\n'
+        '    owner: "Dana"\n'
+        "    status: open\n"
+    )
+    target = tmp_path / "sprint-status.yaml"
+    target.write_text(fixture, encoding="utf-8")
+    proc = _run(
+        ["update", "--file", str(target), "--epic", "1",
+         "--set-action-status", '[{"epic":1,"action":"Same text","status":"done"}]']
+    )
+    assert proc.returncode == 1
+    out = _json(proc)
+    assert out["ok"] is False
+    assert out["restored"] is True
+    assert "ambiguous" in out["error"]
+    assert "Same text" in out["error"]
+    assert "2 matches" in out["error"]
+    assert target.read_text(encoding="utf-8") == fixture
+
+
+def test_set_action_status_rejects_two_entries_hitting_the_same_item(tmp_path):
+    # The id form and the epic/action form can name the same row; applying both
+    # would overcount action_items_updated and hide a conflicting pair.
+    target = _write_action_fixture(tmp_path)
+    payload = json.dumps(
+        [
+            {"id": "epic-1-retro-item-1-x", "status": "done"},
+            {"epic": 1, "action": "Scripted item", "status": "in-progress"},
+        ]
+    )
+    proc = _run(
+        ["update", "--file", str(target), "--epic", "1", "--set-action-status", payload]
+    )
+    assert proc.returncode == 1
+    out = _json(proc)
+    assert out["ok"] is False
+    assert out["restored"] is True
+    assert "same action item" in out["error"]
+    assert target.read_text(encoding="utf-8") == ACTION_FIXTURE
+
+
+def test_entry_with_both_selector_forms_uses_the_id(tmp_path):
+    # A caller that copied a whole item through supplies both. The id is the
+    # precise form and wins; the extra keys are ignored, not rejected. The two
+    # forms are pointed at *different* rows so the precedence is observable:
+    # the id names items[0], the epic/action pair names items[1].
+    target = _write_action_fixture(tmp_path)
+    payload = json.dumps(
+        [
+            {
+                "id": "epic-1-retro-item-1-x",
+                "epic": 1,
+                "action": "Pre-existing item",
+                "owner": "Charlie",
+                "status": "done",
+            }
+        ]
+    )
+    proc = _run(
+        ["update", "--file", str(target), "--epic", "1", "--set-action-status", payload]
+    )
+    assert proc.returncode == 0, proc.stderr
+    assert _json(proc)["action_items_updated"] == 1
+    items = _load(target)["action_items"]
+    assert items[0]["status"] == "done"  # the id's item
+    assert items[1]["status"] == "open"  # the epic/action item, untouched
+
+
+def test_set_action_status_rejects_invalid_status(tmp_path):
+    target = _write_action_fixture(tmp_path)
+    proc = _run(
+        ["update", "--file", str(target), "--epic", "1",
+         "--set-action-status", '[{"id":"epic-1-retro-item-1-x","status":"closed"}]']
+    )
+    assert proc.returncode == 1
+    out = _json(proc)
+    assert out["ok"] is False
+    assert out["restored"] is True
+    assert "closed" in out["error"]
+    # The allowed vocabulary is named so the caller can correct the call.
+    assert "open, in-progress, done" in out["error"]
+    assert target.read_text(encoding="utf-8") == ACTION_FIXTURE
+
+
+def test_set_action_status_rejects_malformed_json(tmp_path):
+    target = _write_action_fixture(tmp_path)
+    proc = _run(
+        ["update", "--file", str(target), "--epic", "1",
+         "--set-action-status", "{not json"]
+    )
+    assert proc.returncode == 1
+    out = _json(proc)
+    assert out["ok"] is False
+    assert out["restored"] is True
+    assert "invalid --set-action-status JSON" in out["error"]
+    assert target.read_text(encoding="utf-8") == ACTION_FIXTURE
+
+
+_SELECTOR_SHAPE_ERROR = (
+    "each --set-action-status entry must have a non-empty string id, "
+    "or an integer epic and a non-empty string action"
+)
+
+
+@pytest.mark.parametrize(
+    ("payload", "expected_error"),
+    [
+        (
+            '{"id":"epic-1-retro-item-1-x","status":"done"}',
+            "--set-action-status must be a JSON array",
+        ),
+        (
+            '["epic-1-retro-item-1-x"]',
+            "each --set-action-status entry must be an object",
+        ),
+        ('[{"status":"done"}]', _SELECTOR_SHAPE_ERROR),
+        (
+            '[{"id":"","status":"done"}]',
+            "each --set-action-status id must be a non-empty string",
+        ),
+        (
+            '[{"id":42,"status":"done"}]',
+            "each --set-action-status id must be a non-empty string",
+        ),
+        (
+            '[{"epic":"1","action":"Pre-existing item","status":"done"}]',
+            _SELECTOR_SHAPE_ERROR,
+        ),
+        (
+            '[{"epic":true,"action":"Pre-existing item","status":"done"}]',
+            _SELECTOR_SHAPE_ERROR,
+        ),
+        ('[{"epic":1,"action":"   ","status":"done"}]', _SELECTOR_SHAPE_ERROR),
+        (
+            # No status key at all: the status validator runs before the selector
+            # validator, so this is the status branch, not the selector branch.
+            '[{"epic":1,"action":"Pre-existing item"}]',
+            "invalid --set-action-status status None",
+        ),
+        (
+            '[{"id":"epic-1-retro-item-1-x","status":3}]',
+            "invalid --set-action-status status 3",
+        ),
+    ],
+    ids=[
+        "not-a-list",
+        "entry-not-an-object",
+        "no-selector",
+        "empty-id",
+        "non-string-id",
+        "string-epic",
+        "bool-epic",
+        "blank-action",
+        "no-status-key",
+        "non-string-status",
+    ],
+)
+def test_set_action_status_rejects_bad_shapes(tmp_path, payload, expected_error):
+    # Each case pins its own message: collapsing the branches into one generic
+    # error would leave a caller unable to tell which part of the array is wrong.
+    target = _write_action_fixture(tmp_path)
+    proc = _run(
+        ["update", "--file", str(target), "--epic", "1",
+         "--set-action-status", payload]
+    )
+    assert proc.returncode == 1
+    out = _json(proc)
+    assert out["ok"] is False
+    assert out["restored"] is True
+    assert expected_error in out["error"], out["error"]
+    assert target.read_text(encoding="utf-8") == ACTION_FIXTURE
+
+
+def test_selectors_are_not_scoped_to_the_epic_flag(tmp_path):
+    # The flag's headline use: epic 2's retro closing epic 1's items. --epic only
+    # names the retro key and stamps appended items; scoping selectors to it would
+    # silently break the documented cross-epic workflow while every same-epic test
+    # kept passing.
+    target = _write_action_fixture(tmp_path)
+    payload = json.dumps(
+        [
+            {"id": "epic-1-retro-item-1-x", "status": "done"},
+            {"epic": 1, "action": "Pre-existing item", "status": "done"},
+        ]
+    )
+    proc = _run(
+        ["update", "--file", str(target), "--epic", "2", "--set-retro-done",
+         "--set-action-status", payload]
+    )
+    assert proc.returncode == 0, proc.stderr
+    assert _json(proc)["action_items_updated"] == 2
+
+    data = _load(target)
+    assert data["development_status"]["epic-2-retrospective"] == "done"
+    items = data["action_items"]
+    assert items[0]["status"] == "done"
+    assert items[1]["status"] == "done"
+    # Epic 2's own item is not swept along.
+    assert items[2]["status"] == "in-progress"
+
+
+def test_legacy_selector_discriminates_on_the_epic(tmp_path):
+    # Two items share the action text "Scripted item" and differ only by epic, so
+    # an epic-blind text match would be ambiguous -- or worse, silently pick one.
+    target = _write_action_fixture(tmp_path)
+    proc = _run(
+        ["update", "--file", str(target), "--epic", "1", "--set-action-status",
+         '[{"epic":2,"action":"Scripted item","status":"done"}]']
+    )
+    assert proc.returncode == 0, proc.stderr
+    assert _json(proc)["action_items_updated"] == 1
+    items = _load(target)["action_items"]
+    assert items[2]["status"] == "done"
+    assert items[0]["status"] == "open"  # the epic-1 namesake, untouched
+
+
+def test_non_mapping_action_item_does_not_crash_the_selector(tmp_path):
+    # A hand-edited scalar in the action_items list must be skipped, not
+    # AttributeError'd into an empty stdout with a traceback.
+    fixture = (
+        "development_status:\n"
+        "  1-1-a: done\n"
+        "  epic-1-retrospective: optional\n"
+        "action_items:\n"
+        '  - "a bare string someone hand-edited in"\n'
+        '  - id: "real"\n'
+        "    epic: 1\n"
+        '    action: "Real item"\n'
+        "    status: open\n"
+    )
+    target = tmp_path / "sprint-status.yaml"
+    target.write_text(fixture, encoding="utf-8")
+    proc = _run(
+        ["update", "--file", str(target), "--epic", "1",
+         "--set-action-status", '[{"id":"real","status":"done"}]']
+    )
+    assert proc.returncode == 0, proc.stderr
+    assert _json(proc)["action_items_updated"] == 1
+    items = _load(target)["action_items"]
+    assert items[0] == "a bare string someone hand-edited in"
+    assert items[1]["status"] == "done"
+
+
+def test_non_mapping_action_item_stays_on_the_json_contract_when_unmatched(tmp_path):
+    # Same guard, reject path: the scalar must not be dereferenced while looking
+    # for a selector that is not there.
+    fixture = (
+        "development_status:\n"
+        "  1-1-a: done\n"
+        "action_items:\n"
+        "  - 42\n"
+    )
+    target = tmp_path / "sprint-status.yaml"
+    target.write_text(fixture, encoding="utf-8")
+    proc = _run(
+        ["update", "--file", str(target), "--epic", "1",
+         "--set-action-status", '[{"epic":1,"action":"Nothing","status":"done"}]']
+    )
+    assert proc.returncode == 1
+    out = _json(proc)  # asserts stdout is JSON and stderr carries no traceback
+    assert out["ok"] is False
+    assert out["restored"] is True
+    assert "no action item matches" in out["error"]
+    assert target.read_text(encoding="utf-8") == fixture
+
+
+def test_boolean_epic_in_the_file_does_not_match_epic_one(tmp_path):
+    # True == 1 in Python, so without the file-side bool guard a hand-edited
+    # "epic: true" row would be silently rewritten by a selector aimed at epic 1.
+    fixture = (
+        "development_status:\n"
+        "  1-1-a: done\n"
+        "action_items:\n"
+        "  - epic: true\n"
+        '    action: "Boolean epic"\n'
+        "    status: open\n"
+    )
+    target = tmp_path / "sprint-status.yaml"
+    target.write_text(fixture, encoding="utf-8")
+    proc = _run(
+        ["update", "--file", str(target), "--epic", "1", "--set-action-status",
+         '[{"epic":1,"action":"Boolean epic","status":"done"}]']
+    )
+    assert proc.returncode == 1
+    out = _json(proc)
+    assert out["ok"] is False
+    assert out["restored"] is True
+    assert "no action item matches" in out["error"]
+    assert target.read_text(encoding="utf-8") == fixture
+
+
+def test_status_write_preserves_every_scalar_style(tmp_path):
+    # The status write must land on the line without re-styling it, whichever way
+    # the file spells the scalar.
+    target = tmp_path / "sprint-status.yaml"
+    target.write_text(STYLE_FIXTURE, encoding="utf-8")
+    payload = json.dumps(
+        [
+            {"id": "double", "status": "done"},
+            {"id": "single", "status": "done"},
+            {"id": "plain", "status": "done"},
+        ]
+    )
+    proc = _run(
+        ["update", "--file", str(target), "--epic", "1", "--date",
+         "01-01-2026 09:00", "--set-action-status", payload]
+    )
+    assert proc.returncode == 0, proc.stderr
+    assert _json(proc)["action_items_updated"] == 3
+
+    before = STYLE_FIXTURE.splitlines()
+    after = target.read_text(encoding="utf-8").splitlines()
+    assert len(before) == len(after)
+    changed = [(b, a) for b, a in zip(before, after) if b != a]
+    assert changed == [
+        ('    status: "open"', '    status: "done"'),
+        ("    status: 'open'", "    status: 'done'"),
+        ("    status: open", "    status: done"),
+    ], changed
+
+
+def test_action_status_vocabulary_is_exactly_the_three():
+    # bmad-sprint-planning is the authority. Widening this tuple would let the
+    # script write a value sprint-planning's status view reports as illegal.
+    assert _module().ACTION_STATUSES == ("open", "in-progress", "done")
+
+
+def test_empty_status_array_is_a_no_op(tmp_path):
+    target = _write_action_fixture(tmp_path)
+    proc = _run(
+        ["update", "--file", str(target), "--epic", "1", "--date",
+         "01-01-2026 09:00", "--set-action-status", "[]"]
+    )
+    assert proc.returncode == 0, proc.stderr
+    assert _json(proc)["action_items_updated"] == 0
+    assert target.read_text(encoding="utf-8") == ACTION_FIXTURE
+
+
+def test_in_progress_item_transitions_to_done(tmp_path):
+    # Every other success case starts from "open"; the middle of the lifecycle
+    # has to work too.
+    target = _write_action_fixture(tmp_path)
+    proc = _run(
+        ["update", "--file", str(target), "--epic", "2", "--set-action-status",
+         '[{"id":"epic-2-retro-item-1-y","status":"done"}]']
+    )
+    assert proc.returncode == 0, proc.stderr
+    assert _json(proc)["action_items_updated"] == 1
+    assert _load(target)["action_items"][2]["status"] == "done"
+
+
+def test_action_items_updated_is_always_reported(tmp_path):
+    # Consumers read the counter unconditionally, so it must be present even when
+    # the flag was not passed.
+    target = _write_fixture(tmp_path)
+    proc = _run(["update", "--file", str(target), "--epic", "1", "--set-retro-done"])
+    assert proc.returncode == 0, proc.stderr
+    assert _json(proc)["action_items_updated"] == 0
+
+
+def test_post_write_status_mismatch_restores(tmp_path, monkeypatch, capsys):
+    # The last line of defence: the written file is re-parsed and every targeted
+    # item is checked. No CLI path can fake a mismatch, so the re-parse is
+    # doctored directly.
+    mod = _module()
+    target = _write_action_fixture(tmp_path)
+    real_load_yaml = mod._load_yaml
+    calls = {"n": 0}
+
+    def flaky(path):
+        yaml, data = real_load_yaml(path)
+        calls["n"] += 1
+        if calls["n"] == 2:  # the post-write re-parse
+            data["action_items"][0]["status"] = "open"
+        return yaml, data
+
+    monkeypatch.setattr(mod, "_load_yaml", flaky)
+    args = mod.build_parser().parse_args(
+        ["update", "--file", str(target), "--epic", "1", "--date", "01-01-2026 09:00",
+         "--set-action-status", '[{"id":"epic-1-retro-item-1-x","status":"done"}]']
+    )
+    with pytest.raises(SystemExit) as excinfo:
+        mod.cmd_update(args)
+    assert excinfo.value.code == 1
+    out = json.loads(capsys.readouterr().out)
+    assert out["ok"] is False
+    assert out["restored"] is True
+    assert "after write" in out["error"]
+    assert target.read_text(encoding="utf-8") == ACTION_FIXTURE
+
+
+if __name__ == "__main__":
+    sys.exit(pytest.main([__file__, "-q"]))