Orchestrata Ultimate › Plans › spec-audit › reverify-2026-10-18 › E-volks-1

Cluster E — Volks (PM / UX / Junior / CodeDirector / Architect) — RE-VERIFY

Source: plans/spec-audit/reverify-2026-10-18/E-volks-1.md at 8a2cb42ad · last changed 2026-10-18 · first committed 2026-10-18 · 295 lines.

Prose pending.

Plan text

Cluster E — Volks (PM / UX / Junior / CodeDirector / Architect) — RE-VERIFY

Read-only re-verification of SPEC-012, 013, 027, 029, 030 against src/orchestrata_ultimate/agents/volks/ on branch components (337 commits ahead of the 3-month-old audits). Judged by code only — the checklists/requirements.md - [ ] boxes are stale, and in two specs the checklist has been renumbered/re-scoped while the spec.md body still carries the old FR/US text (see SPEC-012 and SPEC-013 notes below). All Python evidence came from the AST toolkit (source/symbols/refs), never grep/read of .py.

Main-session findings (already verified elsewhere, trusted here, not re-litigated): SPEC-012 US-004/005 budget half absent · SPEC-012 goal lifecycle LANDED · SPEC-013 REQ-013-010 QA wireframe validation absent · SPEC-030 chmod 0o700 landed.

SPEC-012 PM Volk — PARTIAL

• Specifies: U:PM = scope validation, effort estimation, progress tracking, budget enforcement, iteration summary; advisory-only (never blocks), sits Cx→Ar, routes to U:Ux when has_ui else U:Ar. spec.md body still lists US-001..005
  • REQ-012-001..010; the tracking checklist has been re-scoped to REQ-012-001..050 (adds UI detection, routing, GoalRegistry lifecycle REQ-012-026..040, GoalReportGenerator REQ-012-041..050) and drops the budget/iteration-summary REQs.
• Verified:
  • US-001 Scope validation ✅ — PM_SYSTEM_PROMPT counts FEATURES/ENTITIES/ INTERFACES/DEPLOYMENT with thresholds pm/volk.py:20-36; _handle_scope_review pm/volk.py:234, _parse_scope_result/_parse_scope_status/_parse_estimate pm/volk.py:100-140; verdict carried in scope_data (advisory forward only).
  • US-002 Effort estimation ✅ — _parse_estimate pm/volk.py:109 extracts the ESTIMATE JSON; attached to forward payload as scope_data (_build_forward_packet pm/volk.py:303). REQ-012-010 actual-vs-estimated calibration store is not persisted (minor; same as prior audit).
  • US-003 Progress monitoring ⚠️ — _handle_progress pm/volk.py:346 only consumes inbound progress_update fields into self.metrics + records goal progress (_record_goal_progress pm/volk.py:364); it emits nothing. No progress_update/iteration_stalled emission. self.metrics is write-only.
  • US-004 Budget enforcement ❌ — symbols --pattern PMConfig → 0; symbols --pattern budget_warning → 0; symbols --pattern budget_exceeded → 0.
  • US-005 Iteration summary ❌ — symbols --pattern iteration_summary → 0; not persisted to conversation.md.
  • NFR-002 advisory-only ✅ — _build_forward_packet always forwards, never blocks; unrecognised subject returns None (process pm/volk.py:213).
  • Routing + UI detection ✅ — _detect_has_ui pm/volk.py:70 (keyword scan, case-insensitive); routes U:Ux vs U:Ar pm/volk.py:303-339.
  • Goal lifecycle ✅ (LANDED — trusted, line-confirmed) — GoalRegistry imported pm/volk.py:10, constructed pm/volk.py:199 (composition over injected SessionManagerProtocol context store); GoalReportGenerator wired pm/volk.py:200; _record_goal_progress calls get_active_goal/record_iteration/generate pm/volk.py:364-390. refs GoalRegistry → 1 DEF + 1 prod IMP + 1 prod USE (was 0 refs at 2026-07-14 — no longer orphaned).
• Remaining work / plan:
  • Scope: implement the spec.md-body US-003(emission)/US-004/US-005 half — a PMConfig dataclass (max_llm_calls/max_duration_minutes/max_fix_cycles + scope thresholds), 80%/100% budget_warning/budget_exceeded, an iteration_summary builder + persistence, and progress_update/iteration_stalled emission at stage transitions. Or formally re-spec the spec.md body to drop US-003/004/005 (they are already absent from the re-scoped checklist) if the budget half is a deliberate de-scope — that decision is owed, not the code.
  • Target files: pm/volk.py (+ new pm/config.py / pm/budget.py).
  • Approach: self.metrics already accumulates (llm_calls/design_cycles/ fix_cycles/files_generated/tests_run) — add a config layer + threshold computation + emission. The hard part is the pipeline must feed PM real stage-transition metrics: today nothing sends progress_update into PM, so PM stays write-only even after the config layer lands.
  • Dependencies: orchestrator/pipeline (orchestrator/pipeline_runner.py + CXP subjects) must emit metric events into PM. iteration_stalled (5-min timer) needs a scheduler PM lacks.
  • Effort: L. Risk: med (cross-subsystem event wiring + a timer).
• Evidence log:
  • source agents.volks.pm.volk → full 399-line read; method lines above.
  • symbols --pattern PMConfig|budget_warning|budget_exceeded|iteration_summary → 0 each.
  • refs GoalRegistry → DEF goal_registry.py:99, IMP volk.py:10, USE volk.py:199.
  • symbols --pattern _detect_has_ui → pm/volk.py:70.

SPEC-013 UX Volk — PARTIAL

• Specifies: U:Ux produces UI design artifacts (workflows, component tree, wireframes, design tokens, a11y) only when has_ui; artifacts feed Architect; QA validates the UI against UX wireframes (spec.md REQ-013-010).
• Verified:
  • REQ-013-001/002 identity ✅ — UXVolk(BaseAgent) alias U:Ux, role "UX Designer" ux/volk.py:79-85.
  • REQ-013-003/004 routing ✅ — process handles only ux_design, returns None otherwise ux/volk.py:100.
  • Activation gate ✅ — _handle_ux_design ux/volk.py:115 reads has_ui; _passthrough (false) ux/volk.py:140 vs _design_ui (true) ux/volk.py:182.
  • Artifacts ✅ — UX_SYSTEM_PROMPT 5-step (workflows/components/wireframes/ tokens/a11y) ux/volk.py:12-70; _design_ui stores output in self.ux_design ux/volk.py:197.
  • Feed Architect ✅ — _build_design_packet emits subject ux_complete (not the prior-audit implement) with ux_design in payload ux/volk.py:212-229; Architect extracts ux_design architect/volk.py:221 and injects via _build_ux_section architect/volk.py:621. Divergence from the 2026-07 prior audit is now RESOLVED: the handoff subject was changed to ux_complete to match the spec CXP table (comment at ux/volk.py:225-227).
  • REQ-013-010 QA validates UI vs UX wireframes ❌ — refs ux_design shows production use only in ux/volk.py and architect/volk.py:630/632; zero under qa/. refs wireframe → 0 def/0 import/0 use anywhere in src/. Still OPEN.
• Remaining work / plan:
  • Scope: thread ux_design (wireframe/component/token structure) from Architect through U:Cd → J:Junior → U:Qa, then add a QA check comparing generated UI against the wireframe/component/token spec.
  • Target files: qa/volk.py, qa/_context.py; carriers (codedirector/volk.py, codedirector/implementation.py, junior/volk.py) must preserve ux_design in forwarded payloads (dropped after Architect today).
  • Approach: attach ux_design to QA inbound payload; add an LLM/heuristic check (rendered UI structure vs wireframe sections + declared components + tokens).
  • Dependencies: SPEC-031 QA volk (cross-cluster) — the ux_design carrier chain PM→UX→Ar→Cd→Junior→QA touches every volk's forwarding code.
  • Effort: M. Risk: med (fuzzy LLM-graded "matches wireframe" check; no clean deterministic assertion).
• Evidence log:
  • source agents.volks.ux.volk → full 239-line read.
  • refs ux_design → USE ux/volk.py:88/197/229, architect/volk.py:630/632; none in qa/.
  • refs wireframe → 0 def/0 import/0 use.
  • symbols --pattern UXVolk → class ux/volk.py:79.

SPEC-027 Junior Volk — DONE

• Specifies: J:Junior = converging design review (≤3 cycles) + code generation via DriverFactory + scan_workspace + validate_dependencies.
• Verified (all FR-001…FR-012 / checklist REQ-027-001…070 present):
  • FR-001/003/004/011 design review ✅ — JuniorVolk(BaseAgent) alias J:Junior junior/volk.py:101; process routes design_review+implement junior/volk.py:129; DESIGN_REVIEW_PROMPT C1-C7 + convergence junior/volk.py:29-97; MAX_DESIGN_REVIEW_CYCLES=3 junior/volk.py:28; auto-READY at cycle≥3 _auto_ready junior/volk.py:254.
  • FR-002 LLM temperature 0.0 ✅ — _call_design_review_llm junior/volk.py:288.
  • FR-005 question parsing ✅ — parse_questions junior/volk.py:484, _extract_question_line junior/volk.py:520, _is_section_break junior/volk.py:543.
  • FR-006/007 code gen via driver ✅ — _handle_implement junior/volk.py:198 calls get_driver(volk="J:Junior", workspace=...) then driver.execute junior/volk.py:215-224.
  • FR-008 workspace scan ✅ — scan_workspace junior/volk.py:576 (excludes hidden/__pycache__/Module: dirs, sorted rel paths).
  • FR-009 dependency validation ✅ — validate_dependencies junior/volk.py:619 (AST imports vs pyproject.toml via verification.review.helpers._get_pyproject_deps
    • checks_correctness.check_dependency_declaration; recognises local src/ modules).
  • FR-010 result reporting ✅ — design_feedback→U:Ar _make_feedback_packet junior/volk.py:440; implementation_complete→U:Cd junior/volk.py:236.
  • FR-012 driver-failure handling ✅ — success/output/deps_issues returned; CodeDirector raises TaskExecutionError on success=False (codedirector/volk.py:270).
• Divergence notes (spec text stale, NOT gaps): code routes on subject implement and emits implementation_complete/design_feedback where the spec narrates code_generate/code_generate/result/design_review/result; extends BaseAgent not BaseVolk; no JuniorVolkConfig type. Behaviour matches. Confirms register "clean" (027).
• Remaining work / plan: none functional. Optional: update spec subject names
  • class-hierarchy prose to match code. Effort S (doc-only).
• Evidence log:
  • source agents.volks.junior.volk → full 717-line read.
  • symbols --pattern JuniorVolk|scan_workspace|validate_dependencies|parse_questions → lines above.
  • Register line 22-23 lists 027 as clean.

SPEC-029 CodeDirector Volk — PARTIAL (mostly done; 1 divergence + 1 orphan-pair)

• Specifies: U:Cd = skeleton-first scaffold, Prolog-gated fan-out (swarm/serial), self-review loop that runs deterministic checks first then LLM, QA fix loop.
• Verified:
  • Routing ✅ — CodeDirectorVolk(BaseAgent) alias U:Cd codedirector/volk.py:53; process maps implement/implementation_complete/fix_issues/review_edit codedirector/volk.py:92.
  • Skeleton + fan-out + swarm/serial ✅ — _handle_implement codedirector/volk.py:117 (extract_design_docs → generate_skeleton_files → get_fan_out_decision → swarm/serial); helpers in implementation.py (execute_swarm_path, build_skeleton_prompt, build_fallback_prompt, append_prompt_extras); serial dispatches J:Junior codedirector/volk.py:195-222.
  • Self-review LLM loop ✅ — _run_self_review codedirector/volk.py:481 → self_review_loop review.py:41 → _run_review_cycle/_run_review (LLM-only, via _call_llm_with_tools, SPEC-103 tool loop). PASS→break, cap at MAX_SELF_REVIEW_ISSUES.
  • QA fix loop ✅ — _handle_fix_issues codedirector/volk.py:307, prepare_fix_delegation/handle_fix_return in review.py.
  • ⚠️ DIVERGENCE (FR-017 / REQ-029-064): MAX_SELF_REVIEW_CYCLES = 3 (prompts.py:6) vs spec's stated 99 (spec.md:55,464,677). Register line 73 flagged this; still 3 today. Action = pick authoritative value + update spec; do not blind-change code (99 would be pathologically expensive).
  • ⚠️ ORPHAN-PAIR (FR-013 / REQ-029-062 "deterministic checks first"): NOT wired. self_review_loop imports only SELF_REVIEW_PROMPT/constants (review.py:12-23) and never calls run_deterministic_review. refs run_deterministic_review → 2 DEF, 0 production USE:
    • agents/volks/codedirector/review_checks.py:1277 (the SPEC-029 local copy, traced REQ-029-067/068, 8+ checks: SYNTAX/file_paths/completeness/entry_point/ dependency_declared/no_placeholder/type_hints/docstrings/todo);
    • verification/review/engine.py:53 (the shared verification subsystem engine, re-exported verification/review/__init__.py:15, richer check set). Both are imported only by tests. So the deterministic pass runs nowhere in the U:Cd self-review path. (Junior DOES run a DEPENDENCY_DECLARED-style check via validate_dependencies, so the capability is not wholly dead in the pipeline.)
• Remaining work / plan:
  • Scope: (a) wire run_deterministic_review as the pre-LLM pass in _run_review_cycle, or (b) update spec to reflect intentional LLM-only review; reconcile MAX_SELF_REVIEW_CYCLES 3-vs-99; and consolidate the two run_deterministic_review definitions (codedirector-local copy is the orphan; the verification/review engine is the shared one).
  • Target files: codedirector/review.py (insert deterministic pass) + codedirector/prompts.py + specs/029-*/spec.md; dedupe against verification/review/engine.py.
  • Dependencies: verification/review subsystem (shared deterministic engine) — consolidation, not a point fix.
  • Effort: S (wire) or doc-only. Risk: low.
• Evidence log:
  • source agents.volks.codedirector.prompts → MAX_SELF_REVIEW_CYCLES = 3 (line 6), MAX_SELF_REVIEW_ISSUES = 5 (line 7).
  • source agents.volks.codedirector.review → self_review_loop at :41, no run_deterministic_review import.
  • refs run_deterministic_review → 2 DEF (review_checks.py:1277, engine.py:53), 6 IMP, 14 USE (all test-side), 1 string-literal; 0 production USE.
  • source agents.volks.codedirector.review_checks :1277-1320 and source verification.review.engine :1-90 → the two definitions.

SPEC-030 Architect Volk — DONE (0700 confirmed; orphaned duplicates already deleted)

• Specifies: U:Ar = reasoner-driven 5-artifact design, J:Junior feedback loop, U:Cd escalation, Neo4j monorepo context, project scaffold (0700), UX integration.
• Verified:
  • FR-001/002 routing ✅ — process handles implement/scope_validated/ux_complete → _handle_design, design_feedback → _handle_feedback, review_edit → _handle_review_edit architect/volk.py:178-206.
  • 5-artifact design ✅ — _handle_design architect/volk.py:207 (requirements/ task_summary/original_intent/ux_design/scope_data → _init_project → _build_full_monorepo_context → tool-loop LLM _call_llm_with_tools → _parse_design with blank-section retry + TaskExecutionError fail-loud → _write_design_docs → _make_review_packet).
  • Feedback loop + escalation ✅ — _handle_feedback architect/volk.py:328; _finalize_design architect/volk.py:343 (implement CXP to U:Cd with 5 artifacts + 5 context fields + needs_capability); _iterate_design architect/volk.py:392 (ARCHITECT_UPDATE_TEMPLATE + numbered questions). MAX_DESIGN_CYCLES = 99 architect_prompts.py:12 (consistent with spec).
  • Monorepo context ✅ — ArchitectContextMixin from architect_context.py (import architect/volk.py:23): _build_project_tree_context :42, _scan_filesystem_for_classes (filesystem fallback) :295, _build_full_monorepo_context :389.
  • Project scaffold + 0700 ✅ (item to verify) — _init_project architect_project.py:21 creates 7 subdirs + os.chmod(self.project_dir, 0o700) with OSError guard (architect_project.py:~29), context.json (_write_context_json :52), git init (_git_init :76), uv venv 3.14t (_create_venv :91). Tested: test_architect_project.py:177 (test_init_project_sets_owner_only_perms).
  • UX integration ✅ — ux_design extracted architect/volk.py:221, injected via _build_ux_section architect/volk.py:621.
  • Mixin wiring ✅ — ArchitectProjectMixin imported from architect_project.py (architect/volk.py:25-26) and used at architect/volk.py:151 (refs ArchitectProjectMixin → 1 DEF + 1 prod IMP + 1 prod USE).
  • ORPHAN CLEANUP ✅ (was the 2026-07 remaining work — now DONE): the five orphaned duplicate modules are gone from architect/ — directory now holds only architect_context.py, architect_project.py, architect_prompts.py, __init__.py, volk.py. The prior context_mixin.py, project_mixin.py, context_builder.py, volk_context.py, project_init.py no longer exist, and refs ArchitectProjectMixin shows a single definition (the canonical one).
• Remaining work / plan: none functional. Spec-text tidy only (the spec.md "File Structure" section still lists the 5 deleted modules). Effort S (doc).
• Evidence log:
  • source agents.volks.architect.volk → full 638-line read.
  • source agents.volks.architect.architect_project → _init_project :21, chmod 0o700.
  • source agents.volks.architect.architect_prompts → MAX_DESIGN_CYCLES = 99 :12.
  • refs ArchitectProjectMixin → 1 def (architect_project.py:17), 3 imp, 3 use.
  • symbols --pattern _build_ux_section|_build_full_monorepo_context|_scan_filesystem_for_classes|_build_project_tree_context → lines above.
  • ls src/orchestrata_ultimate/agents/volks/architect/ → 5 files (orphans removed).

Cluster summary table

Cross-cluster dependencies flagged

• SPEC-013 (UX) REQ-013-010 ↔ SPEC-031 (QA): the only genuinely blocked REQ. QA must receive ux_design and gain a UI-vs-wireframe check. Carrier-chain change touches CodeDirector + Junior forwarding too.
• SPEC-012 (PM budget/progress) ↔ orchestrator/pipeline: PM's budget + progress half is inert without the pipeline emitting stage-transition/metric events into PM — self.metrics is write-only today. Half the work lives outside the volk.
• SPEC-029 deterministic review ↔ verification/review subsystem: two run_deterministic_review copies (codedirector-local orphan + shared engine), both 0 production callers; consolidation is a subsystem decision.

Related

• Plans
• Orchestrata Ultimate — project index
• Workflow
• Tasks