Files
gcp_solution_architecture_a…/app/states/execution_state.py
Jonathan Boniface 567aede5ca feat: overlay Skills, and five more Jev decisions (iterations 4 and 5)
Iteration 4:
- Overlay Skills (step 12): an Execution names an organisation's standards
  Skill from the folders the deployment configures; recorded with its version.
  An example standards Skill and an evaluation case that uses it.
- Lessons (step 10): a prove command that compares a run with lessons against
  one without, and triage of evidence an existing lesson already covers.

Iteration 5:
- Step 8: the references of a Specialist's Skills its task needs are named in
  its context as read_first.
- Step 14: a remote MCP server's reply that instructs the agent is withheld;
  the user's own text is flagged as a risk and nothing more.
- Step 15: in a Change request, items only reworded are listed apart from
  real changes.
- Step 19: each Execution's design recommendations are judged when it ends and
  the scores kept in its record. The evaluation takes its rubric from the same
  place.

Each question was calibrated against live Jev; none has run in a case. Steps
6, 7, 9, 13 and 18 stay planned, with the reasons in the plan map.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-09 17:45:56 +01:00

106 lines
4.8 KiB
Python

"""The checkpointed state of one Execution. Plain, JSON-compatible data only."""
from __future__ import annotations
import operator
import re
from pathlib import Path
from typing import Annotated, Any, TypedDict
# A Customer case id becomes a directory name, so it is a short lowercase slug.
CUSTOMER_CASE = re.compile(r"^[a-z0-9](?:[a-z0-9-]{0,62}[a-z0-9])?$")
# Executions started without a Customer case are grouped here, so every Execution's
# files sit under a case.
UNASSIGNED_CASE = "unassigned"
def check_customer_case(customer_case: object) -> str:
"""The Customer case id, defaulting to UNASSIGNED_CASE; a ValueError when it is
not a safe slug."""
if customer_case is None:
return UNASSIGNED_CASE
if not isinstance(customer_case, str) or not CUSTOMER_CASE.match(customer_case):
raise ValueError(
"customer_case must be 1 to 64 lowercase letters, digits or hyphens, "
f"starting and ending with a letter or digit; got {customer_case!r}"
)
return customer_case
def case_dir(output_root: Path, customer_case: str) -> Path:
"""Everything generated for one Customer case."""
return output_root / "deliverables" / "cases" / customer_case
def execution_dir(output_root: Path, execution_id: str, customer_case: str) -> Path:
"""Where one Execution's files go, under its Customer case."""
return case_dir(output_root, customer_case) / "executions" / execution_id
def lessons_file(output_root: Path, execution_id: str, customer_case: str) -> Path:
return (
output_root / "lessons" / "candidates" / customer_case / f"{execution_id}.json"
)
def merge_by_key(
current: dict[str, dict[str, Any]] | None, update: dict[str, dict[str, Any]] | None
) -> dict[str, dict[str, Any]]:
"""Parallel Specialist tasks each write their own Deliverable's entry."""
return {**(current or {}), **(update or {})}
class ExecutionState(TypedDict, total=False):
execution_id: str
session_id: str
customer_case: str # the Customer case this Execution belongs to
intent_version: int # which statement of the case's intent started this Execution
workflow_request: str
risks: list[dict[str, Any]] # flags on what the user wrote, for a person to see
overlay_skills: dict[str, str] # overlay Skills this Execution loads -> version
baseline: dict[str, Any] | None # a Change request's Baseline, read from its files
pre_approved: bool
allow_cloud_read: bool | None
ledger: dict[str, Any] # Ledger.to_dict()
deliverables: dict[str, dict[str, Any]] # kind -> {content, attachments}
conversation: list[dict[str, str]] # {"from": "user" | "orchestrator", "text"}
notes: list[str] # facts for the Orchestrator's next turn
pending_questions: list[dict[str, Any]] # {kind, questions} not yet asked
awaiting_questions: list[dict[str, Any]] # {kind, questions} asked, not answered
answers: dict[str, list[dict[str, Any]]] # kind -> [{questions, reply}]
drafts_shown: list[str] # Deliverables a draft of which the user has been shown
drafts: dict[
str, dict[str, Any]
] # kind -> {content, attachments} awaiting the user
# kind -> working memory its tools keep across attempts (e.g. pillar advice)
working: Annotated[dict[str, dict[str, Any]], merge_by_key]
pending_permission: dict[str, Any] | None # {tier, requested_by}
prompt: dict[str, Any] | None # what the user is being asked
# Specialist outcomes, appended concurrently by parallel Specialist tasks and
# applied to the Ledger by the next Orchestrator turn.
outcomes: Annotated[list[dict[str, Any]], operator.add]
outcomes_applied: int
refusals: list[dict[str, Any]] # the Orchestrator's refused tool calls
events_recorded: int
# Routing (ADR-0007).
last_reply: dict[str, Any] | None # the user's message, until a turn routes it
pending_change: dict[str, Any] | None # a change the user was asked to confirm
awaiting_gap_decision: bool # the user was asked whether to close gaps
validation_settled: int # the validation attempt already decided on
awaiting_limit_decision: bool # the user was told a Revision limit was reached
revision_limit_asked: list[str] # Deliverables the user has been told that about
idle_asks: int # questions put to the user running, with nothing changing between
ask_fingerprint: str # the Ledger's state when the user was last asked
decisions: list[dict[str, Any]] # every routing decision, in order
# How the design recommendations were judged when the Execution ended.
assessment: dict[str, Any] | None
turns: int
status: str # running | completed | completed_with_warnings
warnings: list[str]
scripted_answers: list[list[str]] # [regex, answer], pre-approved runs only