Increment 3 of .scratch/solution-architect-agent/spec.md, test-first. - app/execution/deliverables.py: four Phases, nine Deliverables and their Dependencies declared once, plus per-kind contracts (required headings, attachments) checked by check_submission. - app/execution/ledger.py: pure Ledger enforcing both acceptance thresholds, Phase Approvals (including pre-approved mode and change requests), Revision cascade with withdrawn Approvals, the revision cap with escalation and user override, attempt numbers that reject stale submissions, an ordered event log, and dict round-tripping. - 37 new tests; full suite 102 passed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
318 lines
12 KiB
Python
318 lines
12 KiB
Python
"""The Ledger: every rule code owns about Deliverable progress, Approvals and Revisions.
|
|
|
|
Pure and synchronous: no I/O, no framework types. Invalid requests raise
|
|
LedgerRefusal and leave the Ledger unchanged; tools turn refusals into messages
|
|
the agent can act on.
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
from collections.abc import Iterable
|
|
from dataclasses import asdict, dataclass, field
|
|
from enum import StrEnum
|
|
from typing import Any
|
|
|
|
from app.execution.deliverables import (
|
|
DEPENDENCY_GRAPH,
|
|
PHASE_ORDER,
|
|
DeliverableKind,
|
|
PhaseId,
|
|
deliverables_in,
|
|
)
|
|
|
|
PRE_APPROVED_ACTOR = "pre-approved"
|
|
|
|
|
|
class DeliverableStatus(StrEnum):
|
|
PENDING = "pending"
|
|
IN_PROGRESS = "in_progress"
|
|
SUBMITTED = "submitted"
|
|
|
|
|
|
class PhaseStatus(StrEnum):
|
|
OPEN = "open"
|
|
AWAITING_APPROVAL = "awaiting_approval"
|
|
APPROVED = "approved"
|
|
|
|
|
|
class LedgerRefusal(Exception):
|
|
"""A request the Ledger's rules don't allow. Nothing was changed."""
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class LedgerEvent:
|
|
sequence: int
|
|
type: str # started | released | submitted | approval_requested | approved |
|
|
# changes_requested | reopened | reset | approval_withdrawn | escalated
|
|
subject: str # a DeliverableKind or PhaseId value
|
|
actor: str
|
|
detail: str = ""
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
class ReopenResult:
|
|
reset: tuple[DeliverableKind, ...]
|
|
withdrawn_approvals: tuple[PhaseId, ...]
|
|
escalation: str | None = None
|
|
|
|
|
|
@dataclass
|
|
class _DeliverableRecord:
|
|
status: DeliverableStatus = DeliverableStatus.PENDING
|
|
attempt: int = 0
|
|
revisions: int = 0
|
|
feedback: list[str] = field(default_factory=list)
|
|
|
|
|
|
class Ledger:
|
|
def __init__(self, pre_approved: bool = False, max_revisions: int = 3) -> None:
|
|
self.pre_approved = pre_approved
|
|
self.max_revisions = max_revisions
|
|
self._deliverables = {kind: _DeliverableRecord() for kind in DEPENDENCY_GRAPH}
|
|
self._phases = {phase: PhaseStatus.OPEN for phase in PHASE_ORDER}
|
|
self._events: list[LedgerEvent] = []
|
|
|
|
# --- queries -----------------------------------------------------------------
|
|
|
|
@property
|
|
def events(self) -> tuple[LedgerEvent, ...]:
|
|
return tuple(self._events)
|
|
|
|
def status(self, kind: DeliverableKind) -> DeliverableStatus:
|
|
return self._deliverables[kind].status
|
|
|
|
def phase_status(self, phase: PhaseId) -> PhaseStatus:
|
|
return self._phases[phase]
|
|
|
|
def revisions(self, kind: DeliverableKind) -> int:
|
|
return self._deliverables[kind].revisions
|
|
|
|
def feedback(self, kind: DeliverableKind) -> tuple[str, ...]:
|
|
return tuple(self._deliverables[kind].feedback)
|
|
|
|
def dependencies_met(self, kind: DeliverableKind) -> bool:
|
|
spec = DEPENDENCY_GRAPH[kind]
|
|
for dependency in spec.depends_on:
|
|
dependency_phase = DEPENDENCY_GRAPH[dependency].phase
|
|
if dependency_phase is spec.phase:
|
|
if self.status(dependency) is not DeliverableStatus.SUBMITTED:
|
|
return False
|
|
elif self._phases[dependency_phase] is not PhaseStatus.APPROVED:
|
|
return False
|
|
return True
|
|
|
|
def ready_work(self) -> tuple[DeliverableKind, ...]:
|
|
return tuple(
|
|
kind
|
|
for kind in DEPENDENCY_GRAPH
|
|
if self.status(kind) is DeliverableStatus.PENDING
|
|
and self.dependencies_met(kind)
|
|
)
|
|
|
|
def phases_ready_for_approval(self) -> tuple[PhaseId, ...]:
|
|
return tuple(
|
|
phase
|
|
for phase in PHASE_ORDER
|
|
if self._phases[phase] is PhaseStatus.OPEN and not self._unsubmitted(phase)
|
|
)
|
|
|
|
def can_finish(self) -> bool:
|
|
return self._phases[PHASE_ORDER[-1]] is PhaseStatus.APPROVED
|
|
|
|
# --- delegation and submission -----------------------------------------------
|
|
|
|
def start(
|
|
self, kinds: Iterable[DeliverableKind], actor: str
|
|
) -> dict[DeliverableKind, int]:
|
|
"""Move ready Deliverables in progress; returns the attempt number for each."""
|
|
kinds = list(dict.fromkeys(kinds))
|
|
ready = set(self.ready_work())
|
|
not_ready = [kind for kind in kinds if kind not in ready]
|
|
if not_ready:
|
|
raise LedgerRefusal(
|
|
"Not ready to start: "
|
|
+ ", ".join(self._describe_unready(k) for k in not_ready)
|
|
)
|
|
attempts = {}
|
|
for kind in kinds:
|
|
record = self._deliverables[kind]
|
|
record.status = DeliverableStatus.IN_PROGRESS
|
|
record.attempt += 1
|
|
attempts[kind] = record.attempt
|
|
self._record("started", kind, actor, f"attempt {record.attempt}")
|
|
return attempts
|
|
|
|
def submit(self, kind: DeliverableKind, attempt: int, actor: str) -> None:
|
|
"""Accept the current attempt. Any later start, release or reopen supersedes it."""
|
|
self._require_current_attempt(kind, attempt)
|
|
self._deliverables[kind].status = DeliverableStatus.SUBMITTED
|
|
self._record("submitted", kind, actor, f"attempt {attempt}")
|
|
|
|
def release(self, kind: DeliverableKind, attempt: int, reason: str) -> None:
|
|
"""Return in-progress work to pending (e.g. the Specialist needs input)."""
|
|
self._require_current_attempt(kind, attempt)
|
|
record = self._deliverables[kind]
|
|
record.status = DeliverableStatus.PENDING
|
|
self._record("released", kind, DEPENDENCY_GRAPH[kind].specialist, reason)
|
|
|
|
# --- approvals ---------------------------------------------------------------
|
|
|
|
def request_approval(self, phase: PhaseId, actor: str) -> None:
|
|
if self._phases[phase] is not PhaseStatus.OPEN:
|
|
raise LedgerRefusal(f"Phase {phase} is {self._phases[phase]}, not open")
|
|
unsubmitted = self._unsubmitted(phase)
|
|
if unsubmitted:
|
|
raise LedgerRefusal(
|
|
f"Phase {phase} has unsubmitted Deliverables: {', '.join(unsubmitted)}"
|
|
)
|
|
self._phases[phase] = PhaseStatus.AWAITING_APPROVAL
|
|
self._record("approval_requested", phase, actor)
|
|
if self.pre_approved:
|
|
self.approve(phase, actor=PRE_APPROVED_ACTOR)
|
|
|
|
def approve(self, phase: PhaseId, actor: str) -> None:
|
|
self._require_awaiting(phase)
|
|
self._phases[phase] = PhaseStatus.APPROVED
|
|
self._record("approved", phase, actor)
|
|
|
|
def request_changes(self, phase: PhaseId, feedback: str, actor: str) -> None:
|
|
self._require_awaiting(phase)
|
|
self._phases[phase] = PhaseStatus.OPEN
|
|
self._record("changes_requested", phase, actor, feedback)
|
|
|
|
# --- revisions ---------------------------------------------------------------
|
|
|
|
def reopen(
|
|
self,
|
|
kind: DeliverableKind,
|
|
reason: str,
|
|
actor: str,
|
|
override_cap: bool = False,
|
|
) -> ReopenResult:
|
|
record = self._deliverables[kind]
|
|
if record.status is not DeliverableStatus.SUBMITTED:
|
|
raise LedgerRefusal(
|
|
f"Only submitted Deliverables can be reopened; {kind} is {record.status}"
|
|
)
|
|
if record.revisions >= self.max_revisions and not override_cap:
|
|
escalation = (
|
|
f"{kind} has reached its revision limit ({self.max_revisions}). "
|
|
f"Requested change: {reason}. Ask the user whether to revise it again "
|
|
"or accept it as it stands."
|
|
)
|
|
self._record("escalated", kind, actor, reason)
|
|
return ReopenResult(reset=(), withdrawn_approvals=(), escalation=escalation)
|
|
|
|
record.status = DeliverableStatus.PENDING
|
|
record.revisions += 1
|
|
record.feedback.append(reason)
|
|
self._record("reopened", kind, actor, reason)
|
|
reset = [kind]
|
|
|
|
for dependent in self._dependents_of(kind):
|
|
dependent_record = self._deliverables[dependent]
|
|
if dependent_record.status is DeliverableStatus.PENDING:
|
|
continue
|
|
dependent_record.status = DeliverableStatus.PENDING
|
|
dependent_record.feedback.append(f"Dependency {kind} was revised: {reason}")
|
|
self._record("reset", dependent, actor, f"dependency {kind} reopened")
|
|
reset.append(dependent)
|
|
|
|
withdrawn = []
|
|
for phase in PHASE_ORDER:
|
|
affected = any(DEPENDENCY_GRAPH[k].phase is phase for k in reset)
|
|
if affected and self._phases[phase] is not PhaseStatus.OPEN:
|
|
self._phases[phase] = PhaseStatus.OPEN
|
|
self._record("approval_withdrawn", phase, actor, f"{kind} reopened")
|
|
withdrawn.append(phase)
|
|
|
|
return ReopenResult(reset=tuple(reset), withdrawn_approvals=tuple(withdrawn))
|
|
|
|
# --- persistence -------------------------------------------------------------
|
|
|
|
def to_dict(self) -> dict[str, Any]:
|
|
return {
|
|
"pre_approved": self.pre_approved,
|
|
"max_revisions": self.max_revisions,
|
|
"deliverables": {
|
|
kind.value: {
|
|
"status": record.status.value,
|
|
"attempt": record.attempt,
|
|
"revisions": record.revisions,
|
|
"feedback": list(record.feedback),
|
|
}
|
|
for kind, record in self._deliverables.items()
|
|
},
|
|
"phases": {
|
|
phase.value: status.value for phase, status in self._phases.items()
|
|
},
|
|
"events": [asdict(event) for event in self._events],
|
|
}
|
|
|
|
@classmethod
|
|
def from_dict(cls, data: dict[str, Any]) -> Ledger:
|
|
ledger = cls(
|
|
pre_approved=data["pre_approved"], max_revisions=data["max_revisions"]
|
|
)
|
|
for kind_value, record in data["deliverables"].items():
|
|
ledger._deliverables[DeliverableKind(kind_value)] = _DeliverableRecord(
|
|
status=DeliverableStatus(record["status"]),
|
|
attempt=record["attempt"],
|
|
revisions=record["revisions"],
|
|
feedback=list(record["feedback"]),
|
|
)
|
|
for phase_value, status in data["phases"].items():
|
|
ledger._phases[PhaseId(phase_value)] = PhaseStatus(status)
|
|
ledger._events = [LedgerEvent(**event) for event in data["events"]]
|
|
return ledger
|
|
|
|
# --- internals ---------------------------------------------------------------
|
|
|
|
def _record(self, type_: str, subject: str, actor: str, detail: str = "") -> None:
|
|
self._events.append(
|
|
LedgerEvent(len(self._events) + 1, type_, str(subject), actor, detail)
|
|
)
|
|
|
|
def _unsubmitted(self, phase: PhaseId) -> list[DeliverableKind]:
|
|
return [
|
|
kind
|
|
for kind in deliverables_in(phase)
|
|
if self.status(kind) is not DeliverableStatus.SUBMITTED
|
|
]
|
|
|
|
def _dependents_of(self, kind: DeliverableKind) -> list[DeliverableKind]:
|
|
"""Every Deliverable that depends on `kind`, directly or not, in graph order."""
|
|
dependents: set[DeliverableKind] = set()
|
|
frontier = {kind}
|
|
while frontier:
|
|
frontier = {
|
|
candidate
|
|
for candidate, spec in DEPENDENCY_GRAPH.items()
|
|
if candidate not in dependents and frontier & set(spec.depends_on)
|
|
}
|
|
dependents |= frontier
|
|
return [candidate for candidate in DEPENDENCY_GRAPH if candidate in dependents]
|
|
|
|
def _describe_unready(self, kind: DeliverableKind) -> str:
|
|
status = self.status(kind)
|
|
if status is not DeliverableStatus.PENDING:
|
|
return f"{kind} ({status})"
|
|
return f"{kind} (dependencies not met)"
|
|
|
|
def _require_current_attempt(self, kind: DeliverableKind, attempt: int) -> None:
|
|
record = self._deliverables[kind]
|
|
if (
|
|
record.status is not DeliverableStatus.IN_PROGRESS
|
|
or attempt != record.attempt
|
|
):
|
|
raise LedgerRefusal(
|
|
f"{kind} is {record.status}, not in_progress with attempt {attempt}; "
|
|
"this attempt is not current"
|
|
)
|
|
|
|
def _require_awaiting(self, phase: PhaseId) -> None:
|
|
if self._phases[phase] is not PhaseStatus.AWAITING_APPROVAL:
|
|
raise LedgerRefusal(
|
|
f"Phase {phase} is {self._phases[phase]}, not awaiting_approval"
|
|
)
|