Files
gcp_solution_architecture_a…/.agents/plans/iter-05-jev-decisions/steps/step-12.md
Jonathan Boniface 5bb22d984e
Some checks failed
validation / verify (push) Failing after 8s
fixed multile issues
2026-10-07 17:33:36 +01:00

4.1 KiB

Step 12 — Implementation Detail

Built against a scripted decider. No call has been made to the live Jev service, and no evaluation has run on it: the owner holds evaluation runs until the Jev work is in.

  1. app/nodes/router.py. Router decides an Orchestrator turn in three stages: readings (_read_ledger from the Ledger and data; _read_message and _read_gap from the decider), a disposition by Thresholds (act at 0.75, close at 0.15, choice confidence 0.6), and the playbook in _choose: ordered groups, the strongest action whose conditions hold, escalate when none applies.
  2. Permission stays with the tools. The router calls the same OrchestratorToolbox tools the model did. A refused action is skipped for the rest of the turn and the next one that holds is taken. Past the Revision limit the user is asked.
  3. What Jev is asked (Question objects, batched when they rest on the same evidence):
    • of the user's message: asks_change (noul), change_target (choice over submitted Deliverables), change_clarity (score: vague, partial, specific);
    • of validation gaps: gap_material (noul);
    • of the user's reply about gaps: wants_revision (noul). What is sent is Deliverable names, the count of waiting questions, the user's message, and for gaps the proposed Check statements and unverifiable Check ids.
  4. Rules when Jev gives no answer. A requested change is acted on only when one Deliverable is named outright, otherwise the user is asked which. A free-text reply is treated as an answer. A gap is revised for when a Check cannot be verified or an addition names a real requirement or recommendation id.
  5. A new reading from the run of 2026-10-07: a Check that fails in two validations running is sent to the Target architecture, not the code. That run retried one unimplementable Check as code three times.
  6. Decisions are recorded in the Execution's state under decisions: turn, group, action and what was judged, with confidence.
  7. The reply writer. A new role, agents/reply-writer.md, writes the Approval summary from facts (approval_facts) through one tool. When it fails or is absent, assembled_summary builds the summary from the same facts.
  8. Wiring. ORCHESTRATOR=router (the default) or model; open_assembly builds the router with the decider and the thresholds (JEV_ACT_THRESHOLD, JEV_CLOSE_THRESHOLD, JEV_CONFIDENCE_THRESHOLD). State gained last_reply, pending_change, awaiting_gap_decision, validation_settled and decisions.

Changed from the plan and the ADR's first wording:

  • Jev does not propose the next action. It supplies readings, and the playbook in code picks the action. This follows the owner's triage model and keeps every decision explainable by a rule and a threshold.
  • The model Orchestrator is kept behind ORCHESTRATOR=model. The 40 or so engine tests drive the Ledger's rules by scripting its tool calls in arbitrary order, which the router cannot do. agents/orchestrator.md is therefore unchanged and unused in router mode.
  • An unclear change is confirmed once. If the reply still does not settle it, a named Deliverable is acted on and anything else is dropped.
  • A pre-approved Execution's automatic replies are not routed. There is no user message to read.

Not built from the ADR's routes:

  • A message that starts something (new request, Change request, question about delivered work, out of scope). It needs an entry point that can answer from a case's files, and Change requests (iteration 7).
  • Which Deliverables a Change request reaches. Iteration 7.

Tests: tests/execution/test_router.py (18), tests/test_assembly.py.

Unverified:

  • Whether Jev's answers to these five questions are good enough at these thresholds. The thresholds are the ones in the owner's example and are untuned.
  • Whether the reply writer's summaries are accurate. It is instructed to state only the facts it is given; nothing checks that it does.
  • Run time. The Orchestrator made 31 model requests in the last run; the router makes none, and one small writer call per Approval. No run has measured it.