feat: keep an unchanged description, list conditions, review coverage with Jev

After case 02 (completed at 100%, but with two Revisions of the Target
architecture for gaps validation found one pass at a time):

- A Deliverable stands while what it was written from is unchanged. The
  architecture description is written from the Elements and Relationships,
  so a Revision that only adds or rewords Checks no longer runs the describer.
- Non-functional requirements and recommendations list their conditions,
  one entry per separate thing that must be true; submission requires them.
- A coverage review at submission (JEV_COVERAGE_REVIEW, off by default):
  for each condition, Jev chooses which Check verifies it, or none. Asked as
  one broad yes-or-no per requirement it could not tell a complete design
  from one with known gaps; asked as a choice per condition it raised all
  four known gaps of case 02 and nothing on the complete graph. An opt-in
  live test (LIVE_JEV=1) repeats that.
- The validator is told to report every gap in its first pass.

Plans record the case 02 run and both forms of the review with figures.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
2026-10-07 20:58:38 +01:00
parent f1f6f1b83a
commit 5adc911a82
29 changed files with 1687 additions and 16 deletions

View File

@@ -67,6 +67,29 @@ def read_graph(upstream: Upstream | None) -> TargetArchitecture | None:
return None
def graph_structure(upstream: Upstream | None) -> str | None:
"""The Target architecture's Elements and Relationships, as one comparable value.
What a Deliverable written from the shape of the design, and not from its
Checks, was written from. None when there is no readable graph.
"""
graph = read_graph(upstream)
if graph is None:
return None
return json.dumps(
{
"elements": [
[e.id, e.name, e.product, e.resource_type, e.component]
for e in graph.elements
],
"relationships": [
[r.id, r.source, r.target, r.kind] for r in graph.relationships
],
},
sort_keys=True,
)
def _objects(
text: str, name: str, strings: Sequence[str], lists: Sequence[str] = ()
) -> tuple[list[dict[str, Any]], list[str]]:
@@ -113,6 +136,40 @@ def _repeated(
return problems
def conditions_of(item: Mapping[str, Any]) -> tuple[str, ...]:
"""The separate things a requirement or recommendation asks for.
Each is one statement that a Check can verify on its own. An item written before
conditions were listed is read as one condition: its whole text.
"""
listed = item.get("conditions")
if isinstance(listed, list):
conditions = tuple(
c.strip() for c in listed if isinstance(c, str) and c.strip()
)
if conditions:
return conditions
text = item.get("text")
return (text.strip(),) if isinstance(text, str) and text.strip() else ()
def _lacking_conditions(items: Sequence[Mapping[str, Any]], name: str) -> list[str]:
"""A constraint must say, one by one, what would have to be true for it to be met."""
problems = []
for item in items:
listed = item.get("conditions")
if (
not isinstance(listed, list)
or not listed
or not all(isinstance(c, str) and c.strip() for c in listed)
):
problems.append(
f"{name}: {item['id']} needs `conditions`: a list with one entry "
"for each separate thing it asks for"
)
return problems
def check_requirements(
attachments: Mapping[str, str], upstream: Upstream | None
) -> list[str]:
@@ -126,6 +183,9 @@ def check_requirements(
]
if not items and not problems:
problems.append(f"{name}: lists no requirements")
problems += _lacking_conditions(
[item for item in items if item["kind"] == "non_functional"], name
)
return problems
@@ -189,6 +249,7 @@ def check_recommendations(
problems += _repeated(items, name)
if not items and not problems:
problems.append(f"{name}: lists no recommendations")
problems += _lacking_conditions(items, name)
components = read_list(upstream, "technical_decomposition", COMPONENTS_FILE)
if components:
known = {item["id"] for item in components}

View File

@@ -28,6 +28,7 @@ from app.workflows.chain import (
check_requirements,
check_target_architecture,
check_verdicts,
graph_structure,
)
from app.workflows.target_architecture import GRAPH_ATTACHMENT
@@ -72,6 +73,10 @@ class DeliverableSpec:
# files are its working copy, kept across attempts and attached on submission.
# Another kind: a fresh copy of that Deliverable's files on every attempt.
working_copy: DeliverableKind | None = None
# What the Deliverable is written from, as one comparable value. When a Revision
# upstream leaves that value as it was, the last submission still stands and the
# Specialist is not run again.
written_from: Callable[[Upstream | None], str | None] | None = None
def contract(self) -> dict[str, list[str]]:
"""What a submission must contain, as plain data for the Specialist's context."""
@@ -146,6 +151,9 @@ DEPENDENCY_GRAPH: Mapping[DeliverableKind, DeliverableSpec] = {
"describer",
depends_on=(_K.TARGET_ARCHITECTURE,),
sections=("Components", "Flow"),
# It describes the Elements and how they connect. A Revision that only
# adds or rewords Checks leaves it true.
written_from=graph_structure,
),
DeliverableSpec(
_K.DEPLOYMENT_GUIDANCE,

View File

@@ -18,7 +18,13 @@ from typing import Any, cast
from langgraph.graph import END, START, StateGraph
from app.adk.runtime import AgentRuntime, RoleSpec, RunLimiter, ToolFactory
from app.adk.runtime import (
AgentRuntime,
RoleSpec,
RunLimiter,
SubmissionReview,
ToolFactory,
)
from app.nodes.execution_nodes import make_execution_nodes
from app.nodes.router import OrchestratorPolicy
from app.recorder import ExecutionRecorder
@@ -36,6 +42,7 @@ def build_execution_graph(
limiter: RunLimiter | None = None,
skill_versions: Mapping[str, str] | None = None,
orchestrator: OrchestratorPolicy | None = None,
submission_review: SubmissionReview | None = None,
) -> StateGraph:
nodes = make_execution_nodes(
runtime=runtime,
@@ -47,6 +54,7 @@ def build_execution_graph(
limiter=limiter,
skill_versions=skill_versions,
orchestrator=orchestrator,
submission_review=submission_review,
)
graph = StateGraph(ExecutionState)