Add typed verification attempt identity

Status	File	+	-
M	`src/loader/runtime/dod.py`	51	0
M	`src/loader/runtime/finalization.py`	44	4
M	`src/loader/runtime/tool_batches.py`	19	0
M	`src/loader/runtime/verification_observations.py`	24	0
M	`tests/test_dod.py`	17	0
M	`tests/test_finalization.py`	16	0
M	`tests/test_tool_batches.py`	25	0
M	`tests/test_verification_observations.py`	6	0

src/loader/runtime/dod.pymodified

  from ..llm.base import ToolCall
  from ..tools.shell_tools import BashTool
 +from .verification_observations import VerificationAttempt, verification_attempt_id
  TaskSize = Literal["small", "standard", "large"]
  DoDStatus = Literal["draft", "in_progress", "verifying", "fixing", "done", "failed"]
      line_changes: int = 0
      storage_path: str | None = None
      last_verification_result: str | None = None
 +    verification_attempt_counter: int = 0
 +    active_verification_attempt_id: str | None = None
 +    active_verification_attempt_number: int | None = None
      current_mode: str = "execute"
      mode_history: list[str] = field(default_factory=list)
      clarify_brief: str | None = None
              line_changes=int(data.get("line_changes", 0)),
              storage_path=data.get("storage_path"),
              last_verification_result=data.get("last_verification_result"),
 +            verification_attempt_counter=int(data.get("verification_attempt_counter", 0)),
 +            active_verification_attempt_id=data.get("active_verification_attempt_id"),
 +            active_verification_attempt_number=(
 +                int(data["active_verification_attempt_number"])
 +                if data.get("active_verification_attempt_number") is not None
 +                else None
 +            ),
              current_mode=data.get("current_mode", "execute"),
              mode_history=list(data.get("mode_history", [])),
              clarify_brief=data.get("clarify_brief"),
      return "\n".join(lines)
 +def ensure_active_verification_attempt(dod: DefinitionOfDone) -> VerificationAttempt:
 +    """Return the current verification attempt, synthesizing one if needed."""
++
 +    if (
 +        dod.active_verification_attempt_id
 +        and dod.active_verification_attempt_number is not None
 +    ):
 +        return VerificationAttempt(
 +            attempt_id=dod.active_verification_attempt_id,
 +            attempt_number=dod.active_verification_attempt_number,
 +        )
++
 +    next_number = max(int(dod.verification_attempt_counter or 0), 1)
 +    dod.verification_attempt_counter = next_number
 +    dod.active_verification_attempt_number = next_number
 +    dod.active_verification_attempt_id = verification_attempt_id(next_number)
 +    return VerificationAttempt(
 +        attempt_id=dod.active_verification_attempt_id,
 +        attempt_number=next_number,
 +    )
++
++
 +def begin_new_verification_attempt(
 +    dod: DefinitionOfDone,
 +    *,
 +    supersedes_attempt_id: str | None = None,
 +) -> VerificationAttempt:
 +    """Start the next verification attempt and mark it as active."""
++
 +    next_number = max(int(dod.verification_attempt_counter or 0), 0) + 1
 +    dod.verification_attempt_counter = next_number
 +    dod.active_verification_attempt_number = next_number
 +    dod.active_verification_attempt_id = verification_attempt_id(next_number)
 +    return VerificationAttempt(
 +        attempt_id=dod.active_verification_attempt_id,
 +        attempt_number=next_number,
 +        supersedes_attempt_id=supersedes_attempt_id,
 +    )
++
++
  class DefinitionOfDoneStore:
      """Persist DoD state to `.loader/dod/`."""

src/loader/runtime/finalization.pymodified

      VerificationEvidence,
      build_verification_summary,
      derive_verification_commands,
 +    ensure_active_verification_attempt,
+ )
  from .events import AgentEvent, TurnSummary
  from .evidence_provenance import (
              summary=summary,
+         )
          if dod.verification_commands:
 +            attempt = ensure_active_verification_attempt(dod)
              dod.last_verification_result = VerificationObservationStatus.PENDING.value
              self.dod_store.save(dod)
              append_verification_timeline_entry(
                      for command in dod.verification_commands[:2]
                  ],
                  evidence_provenance=_pending_verification_provenance(dod),
 -                verification_observations=_pending_verification_observations(dod),
 +                verification_observations=_pending_verification_observations(
 +                    dod,
 +                    attempt_id=attempt.attempt_id,
 +                    attempt_number=attempt.attempt_number,
 +                ),
+             )
          verification_passed = await self.verify_definition_of_done(
              dod=dod,
          verification_observations = _verification_result_observations(
              dod,
              passed=verification_passed,
 +            attempt_id=dod.active_verification_attempt_id,
 +            attempt_number=dod.active_verification_attempt_number,
+         )
          if verification_passed:
              passed_provenance = _verification_result_provenance(dod, passed=True)
          dod.status = "verifying"
          self.dod_store.save(dod)
          await self.emit_dod_status(emit, dod)
 +        attempt = ensure_active_verification_attempt(dod)
          if not dod.verification_commands:
              missing_provenance = _missing_verification_provenance()
 -            missing_observations = _missing_verification_observations()
 +            missing_observations = _missing_verification_observations(
 +                attempt_id=attempt.attempt_id,
 +                attempt_number=attempt.attempt_number,
 +            )
              append_verification_timeline_entry(
                  self.context,
                  summary,
                  kind=_classify_verification_kind(command),
+             )
              dod.evidence.append(evidence)
 -            observation = _verification_observation_from_evidence(evidence)
 +            observation = _verification_observation_from_evidence(
 +                evidence,
 +                attempt_id=attempt.attempt_id,
 +                attempt_number=attempt.attempt_number,
 +            )
              provenance = _verification_provenance_from_evidence(evidence)
              append_verification_timeline_entry(
                  self.context,
      dod: DefinitionOfDone,
      *,
      passed: bool,
 +    attempt_id: str | None,
 +    attempt_number: int | None,
  ) -> list[VerificationObservation]:
      entries: list[VerificationObservation] = []
      target_status = (
                  kind=evidence.kind,
                  exit_code=evidence.exit_code,
                  detail=_verification_detail(evidence),
 +                attempt_id=attempt_id,
 +                attempt_number=attempt_number,
+             )
+         )
                  summary=f"verification did not produce an observed result for `{command}`",
                  command=command,
                  kind=_classify_verification_kind(command),
 +                attempt_id=attempt_id,
 +                attempt_number=attempt_number,
+             )
+         )
          VerificationObservation(
              status=VerificationObservationStatus.MISSING.value,
              summary="verification commands were still missing at execution time",
 +            attempt_id=attempt_id,
 +            attempt_number=attempt_number,
+         )
+     ]
  def _verification_observation_from_evidence(
      evidence: VerificationEvidence,
 +    *,
 +    attempt_id: str | None,
 +    attempt_number: int | None,
  ) -> VerificationObservation:
      command = evidence.command or "verification"
      return VerificationObservation(
          kind=evidence.kind,
          exit_code=evidence.exit_code,
          detail=_verification_detail(evidence),
 +        attempt_id=attempt_id,
 +        attempt_number=attempt_number,
+     )
+     ]
 -def _missing_verification_observations() -> list[VerificationObservation]:
 +def _missing_verification_observations(
 +    *,
 +    attempt_id: str | None,
 +    attempt_number: int | None,
 +) -> list[VerificationObservation]:
      return [
          VerificationObservation(
              status=VerificationObservationStatus.MISSING.value,
              summary="verification commands were still missing at execution time",
 +            attempt_id=attempt_id,
 +            attempt_number=attempt_number,
+         )
+     ]
  def _pending_verification_observations(
      dod: DefinitionOfDone,
 +    *,
 +    attempt_id: str | None,
 +    attempt_number: int | None,
  ) -> list[VerificationObservation]:
      observations: list[VerificationObservation] = []
      for command in dod.verification_commands:
                  status=VerificationObservationStatus.PENDING.value,
                  summary=f"verification pending for `{command}`",
                  command=command,
 +                attempt_id=attempt_id,
 +                attempt_number=attempt_number,
+             )
+         )
      return observations

src/loader/runtime/tool_batches.pymodified

  from .dod import (
      DefinitionOfDone,
      DefinitionOfDoneStore,
 +    begin_new_verification_attempt,
      derive_verification_commands,
 +    ensure_active_verification_attempt,
      is_state_mutating_tool_call,
      record_successful_tool_call,
+ )
      tool_call: ToolCall,
  ) -> None:
      detail = _stale_verification_detail(tool_call)
 +    stale_attempt = ensure_active_verification_attempt(dod)
 +    next_attempt = begin_new_verification_attempt(
 +        dod,
 +        supersedes_attempt_id=stale_attempt.attempt_id,
 +    )
      append_verification_timeline_entry(
          context,
          summary,
          verification_observations=_stale_verification_observations(
              dod,
              detail=detail,
 +            stale_attempt_id=stale_attempt.attempt_id,
 +            stale_attempt_number=stale_attempt.attempt_number,
 +            superseded_by_attempt_id=next_attempt.attempt_id,
          ),
+     )
      dod.last_verification_result = VerificationObservationStatus.STALE.value
      if not commands:
          return
 +    attempt = begin_new_verification_attempt(dod)
      detail = _stale_verification_detail(tool_call)
      append_verification_timeline_entry(
          context,
                  command=command,
                  kind="runtime",
                  detail=detail,
 +                attempt_id=attempt.attempt_id,
 +                attempt_number=attempt.attempt_number,
+             )
              for command in commands
          ],
      dod: DefinitionOfDone,
      *,
      detail: str,
 +    stale_attempt_id: str,
 +    stale_attempt_number: int,
 +    superseded_by_attempt_id: str,
  ) -> list[VerificationObservation]:
      return [
          VerificationObservation(
              command=command,
              kind="runtime",
              detail=detail,
 +            attempt_id=stale_attempt_id,
 +            attempt_number=stale_attempt_number,
 +            supersedes_attempt_id=superseded_by_attempt_id,
+         )
          for command in _stale_verification_commands(dod)
+     ]

src/loader/runtime/verification_observations.pymodified

  from typing import Any
 +@dataclass(slots=True, frozen=True)
 +class VerificationAttempt:
 +    """Identity for one verification attempt across lifecycle events."""
++
 +    attempt_id: str
 +    attempt_number: int
 +    supersedes_attempt_id: str | None = None
++
++
  class VerificationObservationStatus(StrEnum):
      """How one verification observation resolved at runtime."""
      kind: str | None = None
      exit_code: int | None = None
      detail: str | None = None
 +    attempt_id: str | None = None
 +    attempt_number: int | None = None
 +    supersedes_attempt_id: str | None = None
      def to_dict(self) -> dict[str, Any]:
          """Serialize one observation for persisted runtime state."""
              "kind": self.kind,
              "exit_code": self.exit_code,
              "detail": self.detail,
 +            "attempt_id": self.attempt_id,
 +            "attempt_number": self.attempt_number,
 +            "supersedes_attempt_id": self.supersedes_attempt_id,
+         }
      @classmethod
              kind=_optional_text(data.get("kind")),
              exit_code=_optional_int(data.get("exit_code")),
              detail=_optional_text(data.get("detail")),
 +            attempt_id=_optional_text(data.get("attempt_id")),
 +            attempt_number=_optional_int(data.get("attempt_number")),
 +            supersedes_attempt_id=_optional_text(data.get("supersedes_attempt_id")),
+         )
 +def verification_attempt_id(attempt_number: int) -> str:
 +    """Build the canonical persisted verification-attempt identifier."""
++
 +    return f"verification-attempt-{attempt_number}"
++
++
  def normalize_verification_observation_status(value: Any) -> str:
      """Coerce persisted observation statuses into the canonical enum set."""

tests/test_dod.pymodified

  from loader.llm.base import ToolCall
  from loader.runtime.dod import (
      DefinitionOfDoneStore,
 +    begin_new_verification_attempt,
      create_definition_of_done,
      derive_verification_commands,
      determine_task_size,
 +    ensure_active_verification_attempt,
      record_successful_tool_call,
+ )
      dod.retry_count = 1
      dod.verification_commands = ["python hello.py"]
      dod.touched_files = [str(tmp_path / "hello.py")]
 +    attempt = begin_new_verification_attempt(dod)
      saved_path = store.save(dod)
      reloaded = store.load(saved_path)
      assert reloaded.retry_count == 1
      assert reloaded.verification_commands == ["python hello.py"]
      assert reloaded.touched_files == [str(tmp_path / "hello.py")]
 +    assert reloaded.active_verification_attempt_id == attempt.attempt_id
 +    assert reloaded.active_verification_attempt_number == attempt.attempt_number
++
++
 +def test_ensure_active_verification_attempt_rehydrates_missing_active_attempt() -> None:
 +    dod = create_definition_of_done("Verify the runtime output.")
 +    dod.verification_attempt_counter = 2
++
 +    attempt = ensure_active_verification_attempt(dod)
++
 +    assert attempt.attempt_id == "verification-attempt-2"
 +    assert attempt.attempt_number == 2
 +    assert dod.active_verification_attempt_id == "verification-attempt-2"
 +    assert dod.active_verification_attempt_number == 2
  def test_verification_command_derivation_prefers_runtime_evidence(tmp_path: Path) -> None:

tests/test_finalization.pymodified

      assert [item.status for item in result.verification_observations] == [
          VerificationObservationStatus.PASSED.value
+     ]
 +    assert result.verification_observations[0].attempt_id == "verification-attempt-1"
 +    assert result.verification_observations[0].attempt_number == 1
      assert result.verification_observations[0].command == "uv run pytest -q"
      assert result.verification_observations[0].detail == "219 passed"
      assert summary.verification_status == "passed"
      assert [item.status for item in session.workflow_timeline[-2].verification_observations] == [
          VerificationObservationStatus.PENDING.value
+     ]
 +    assert (
 +        session.workflow_timeline[-2].verification_observations[0].attempt_id
 +        == "verification-attempt-1"
 +    )
      assert session.workflow_timeline[-2].verification_observations[0].command == (
          "uv run pytest -q"
+     )
      assert [item.status for item in session.workflow_timeline[-1].verification_observations] == [
          VerificationObservationStatus.PASSED.value
+     ]
 +    assert (
 +        session.workflow_timeline[-1].verification_observations[0].attempt_id
 +        == "verification-attempt-1"
 +    )
  @pytest.mark.asyncio
      assert [item.status for item in result.verification_observations] == [
          VerificationObservationStatus.MISSING.value
+     ]
 +    assert result.verification_observations[0].attempt_id == "verification-attempt-1"
 +    assert result.verification_observations[0].attempt_number == 1
      assert [item.summary for item in result.verification_observations] == [
          "verification commands were still missing at execution time"
+     ]
      assert [item.status for item in session.workflow_timeline[-1].verification_observations] == [
          VerificationObservationStatus.MISSING.value
+     ]
 +    assert (
 +        session.workflow_timeline[-1].verification_observations[0].attempt_id
 +        == "verification-attempt-1"
 +    )
      assert session.messages[-1].role == Role.USER
      assert session.messages[-1].content.startswith("[DEFINITION OF DONE CHECK FAILED]")

tests/test_tool_batches.pymodified

      assert dod.last_verification_result == "planned"
      assert dod.verification_commands
      assert "Collect verification evidence" in dod.pending_items
 +    assert dod.active_verification_attempt_id == "verification-attempt-1"
 +    assert dod.active_verification_attempt_number == 1
      assert summary.workflow_timeline[-1].reason_code == "verification_planned"
      assert summary.workflow_timeline[-1].policy_outcome == "planned"
      assert summary.workflow_timeline[-1].verification_observations[0].status == "planned"
 +    assert (
 +        summary.workflow_timeline[-1].verification_observations[0].attempt_id
 +        == "verification-attempt-1"
 +    )
 +    assert (
 +        summary.workflow_timeline[-1].verification_observations[0].attempt_number == 1
 +    )
  @pytest.mark.asyncio
      dod = create_definition_of_done("Update README and verify it still works.")
      dod.verification_commands = ["uv run pytest -q"]
      dod.last_verification_result = "passed"
 +    dod.verification_attempt_counter = 1
 +    dod.active_verification_attempt_id = "verification-attempt-1"
 +    dod.active_verification_attempt_number = 1
      dod.evidence = [
          VerificationEvidence(
              command="uv run pytest -q",
      assert dod.evidence == []
      assert "Collect verification evidence" in dod.pending_items
      assert "Collect verification evidence" not in dod.completed_items
 +    assert dod.active_verification_attempt_id == "verification-attempt-2"
 +    assert dod.active_verification_attempt_number == 2
      assert summary.workflow_timeline[-1].reason_code == "verification_stale"
      assert summary.workflow_timeline[-1].policy_outcome == "stale"
      assert summary.workflow_timeline[-1].verification_observations[0].status == "stale"
 +    assert (
 +        summary.workflow_timeline[-1].verification_observations[0].attempt_id
 +        == "verification-attempt-1"
 +    )
 +    assert (
 +        summary.workflow_timeline[-1].verification_observations[0].attempt_number == 1
 +    )
 +    assert (
 +        summary.workflow_timeline[-1].verification_observations[0].supersedes_attempt_id
 +        == "verification-attempt-2"
 +    )
      assert (
          summary.workflow_timeline[-1].verification_observations[0].command
          == "uv run pytest -q"

tests/test_verification_observations.pymodified


                 "kind": "test",
                 "exit_code": 0,
                 "detail": "219 passed",
+                "attempt_id": "verification-attempt-3",
+                "attempt_number": 3,
+                "supersedes_attempt_id": "verification-attempt-2",
             }
         ]
     )

             kind="test",
             exit_code=0,
             detail="219 passed",
+            attempt_id="verification-attempt-3",
+            attempt_number=3,
+            supersedes_attempt_id="verification-attempt-2",
         )
     ]
 

`@@ -27,6 +27,9 @@` def test_normalize_verification_observations_round_trips_entries() -> None:
27	27	"kind": "test",
28	28	"exit_code": 0,
29	29	"detail": "219 passed",
	30	+ "attempt_id": "verification-attempt-3",
	31	+ "attempt_number": 3,
	32	+ "supersedes_attempt_id": "verification-attempt-2",
30	33	}
31	34	]
32	35	)
`@@ -39,6 +42,9 @@` def test_normalize_verification_observations_round_trips_entries() -> None:
39	42	kind="test",
40	43	exit_code=0,
41	44	detail="219 passed",
	45	+ attempt_id="verification-attempt-3",
	46	+ attempt_number=3,
	47	+ supersedes_attempt_id="verification-attempt-2",
42	48	)
43	49	]
44	50

tenseleyflow/loader / `59470aa`

8 changed files