Orchestrata Ultimate › Plans › spec-audit › E-volks-1

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

Source: plans/spec-audit/E-volks-1.md at 8a2cb42ad · last changed 2026-07-27 · first committed 2026-07-04 · 247 lines.

Prose pending.

Plan text

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

Read-only audit of SPEC-012, 013, 027, 029, 030 against src/orchestrata_ultimate/agents/volks/. Judged by code, not checklist markers. Prior work in docs/spec-gap-register.md already audited all five of these specs — this pass CONFIRMS/UPDATES against current code and cites the register per _METHOD.md rule 5.

Note on except A, B: syntax in pm/volk.py (lines 106/111/122): this is valid PEP 758 parenthesis-free except in Python 3.14 — not a bug, not flagged.

SPEC-012 PM Volk — PARTIAL

• Specifies: U:PM = scope validation, effort estimation, progress tracking, budget enforcement, iteration summary; advisory-only, sits Cx→Ar. Config via a PMConfig dataclass (max_llm_calls/duration/fix_cycles + scope thresholds).
• Verified:
  • US-001 Scope validation ✅ — LLM-driven; PM_SYSTEM_PROMPT counts features/entities/interfaces/deployment + thresholds pm/volk.py:16-36; _handle_scope_review pm/volk.py:220, _parse_scope_result :141. Verdict carried in scope_data, not a literal scope_validated/scope_warning CXP subject (advisory forward only).
  • US-002 Effort estimation ✅ — _parse_estimate pm/volk.py:94 extracts the ESTIMATE JSON; attached to forward packet payload as scope_data (_build_forward_packet :292). No actual-vs-estimated calibration store (REQ-012-010) — not persisted.
  • US-003 Progress monitoring ❌ — _handle_progress pm/volk.py:339 only copies inbound fields into self.metrics; emits nothing. No progress_update, no iteration_stalled. self.metrics (:173) is write-only.
  • US-004 Budget enforcement ❌ — no PMConfig (symbols --pattern PMConfig → 0 symbols), no max_llm_calls/duration/fix_cycles thresholds, no budget_warning/budget_exceeded (0 grep hits under pm/).
  • US-005 Iteration summary ❌ — no iteration_summary dict/event; not persisted to conversation.md (0 hits).
  • NFR-002 advisory-only ✅ — always forwards, never blocks (:243).
  • Routing ✅ — has_ui detection _detect_has_ui :67; routes U:Ux vs U:Ar :300.
• Remaining work / plan:
  • Scope: add PMConfig dataclass (spec §Configuration), threshold logic (80%/100% of llm_calls/duration/fix_cycles), budget_warning/budget_exceeded emission, progress_update at stage transitions, and a structured iteration_summary emitter + persistence. self.metrics already exists as the accumulator; the emission + config layer is what's missing.
  • Target files: pm/volk.py (+ likely a new pm/budget.py / pm/config.py).
  • Approach: define PMConfig; have _handle_progress compute % consumed vs config and emit warning/exceeded packets; add an iteration_summary builder fed by self.metrics. Crucially the pipeline must feed PM real metrics — today nothing sends progress_update packets to PM, so PM stays write-only even after the config layer lands.
  • Dependencies: orchestrator/pipeline (orchestrator/pipeline_runner.py + CXP subjects) must emit stage-transition/metric events into PM. This is the hard coupling — the PM budget half is only half a code change; the other half is pipeline wiring.
  • Effort: L. Risk: med — needs cross-subsystem event wiring, and "iteration_stalled after 5 min" needs a timer/scheduler that PM currently lacks.
• Also: ORPHANED — pm/goal_registry.py (GoalRegistry 0 refs) and pm/goal_report.py (GoalReport 0 external imports, 19 self-uses) implement a goal feature not in current SPEC-012 (register line 80). Deletion or spec-expansion candidate.
• Evidence log:
  • symbols --pattern PMConfig → 0 symbols.
  • grep budget_warning|budget_exceeded|iteration_summary|iteration_stalled pm/ → only inbound progress_update subject at volk.py:200,337.
  • refs GoalRegistry → 1 def, 0 use; refs GoalReport → 0 external imports.
  • Read pm/volk.py full (338 lines).

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 and QA validates the UI against UX wireframes (REQ-013-010).
• Verified:
  • REQ-013-001 activation gate ✅ — has_ui check ux/volk.py:119; _passthrough when false :143.
  • REQ-013-002…007 artifacts ✅ — UX_SYSTEM_PROMPT 5-step (workflows / components / wireframes / tokens / a11y) ux/volk.py:11-65; _design_ui :186 stores output in self.ux_design.
  • REQ-013-008/009 feed Architect ✅ — ux_design in outbound payload :230 → consumed by Architect architect/volk.py:102, injected via _build_ux_section architect/volk.py:325 and volk_context.py:40. Also flows to KG (context_injector.py:30) and artifact store (artifact_store.py:36).
  • REQ-013-010 QA validates UI vs UX wireframes ❌ — 0 hits for ux_design/wireframe/accessibility/design_token/wcag under qa/; ux_design is never threaded past the Architect to the QA volk (register line 67, confirmed against current code).
  • Minor divergence (spec stale, not a gap): UX forwards with subject "implement" (_passthrough :154, _build_design_packet :222), NOT the spec's ux_complete. Functionally fine — Architect handles implement / scope_validated / ux_complete identically (architect/volk.py:87) and reads ux_design from payload regardless. The spec CXP table (ux_complete) is out of date. _build_design_packet also has a stale @traces comment claiming subject ux_complete while emitting implement.
• Remaining work / plan:
  • Scope: thread ux_design (and the wireframe/component/token structure) from the Architect's implement packet through U:Cd → U:Qa so QA receives it, then add a QA check that validates generated UI files against the wireframe / component hierarchy / token spec.
  • Target files: qa/volk.py, qa/_context.py; ensure carriers (codedirector/volk.py, codedirector/implementation.py, junior/volk.py) preserve ux_design in forwarded payloads (currently dropped after Architect).
  • Approach: attach ux_design to the QA inbound payload; add an LLM/heuristic check comparing rendered UI structure vs wireframe sections + declared components + token usage. Low severity (register), but a real REQ.
  • Dependencies: SPEC-031 QA volk (cross-cluster) — this is the primary hand-off. The ux_design carrier chain PM→UX→Ar→Cd→Junior→QA touches every volk's payload-forwarding code.
  • Effort: M. Risk: med — "UI matches wireframe" is a fuzzy, LLM-graded check; deterministic QA has no clean assertion for it.
• Evidence log:
  • grep -ni ux_design|wireframe|accessibility|design_token|wcag qa/ → NONE.
  • grep ux_design src/ → produced by UX, consumed only up to Architect + KG.
  • Read ux/volk.py full (241 lines); architect/volk.py:77-106.

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 present):
  • FR-001/003/004/011 design review ✅ — routed junior/volk.py:125; DESIGN_REVIEW_PROMPT C1-C7 + convergence rules :31-71; MAX_DESIGN_REVIEW_CYCLES=3 :29; auto-READY at cycle≥3 _auto_ready :240.
  • FR-002 LLM temperature 0.0 ✅ — _call_design_review_llm :291.
  • FR-005 question parsing ✅ — parse_questions numbered+bulleted :482, _extract_question_line :518, _is_section_break :543.
  • FR-006/007 code gen via driver ✅ — get_driver :199 + driver.execute :202.
  • FR-008 workspace scan ✅ — scan_workspace :574 (excludes hidden/__pycache__/ Module:, sorted rel paths).
  • FR-009 dependency validation ✅ — validate_dependencies :617 (AST imports vs pyproject.toml, recognises local src/ modules).
  • FR-010 result reporting ✅ — design_feedback→U:Ar _make_feedback_packet :437; implementation_complete→U:Cd :216.
• 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 (pydantic), not BaseVolk; no JuniorVolkConfig type. These are naming/base-class cosmetics — behaviour matches. Confirms register "clean".
• Remaining work / plan: none functional. Optional: update spec subject names + class-hierarchy prose to match code. Effort S (doc-only).
• Evidence log: Read junior/volk.py full (712 lines); register line 22-23 lists 027 as clean.

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

• Specifies: U:Cd = skeleton-first scaffold, Prolog-gated fan-out (swarm/serial), self-review loop that runs deterministic checks first then LLM, and QA fix loop.
• Verified:
  • Routing ✅ — process maps implement/implementation_complete/fix_issues codedirector/volk.py:91.
  • Skeleton + fan-out + swarm/serial ✅ — _handle_implement :106, helpers in implementation.py (extract_design_docs / generate_skeleton_files / get_fan_out_decision / execute_swarm_path).
  • Self-review LLM loop ✅ — self_review_loop review.py:35; SELF_REVIEW_PROMPT prompts.py:55; wired from volk.py:330.
  • QA fix loop ✅ — _handle_fix_issues :277, prepare_fix_delegation/ handle_fix_return in review.py.
  • ⚠️ DIVERGENCE (FR-017): MAX_SELF_REVIEW_CYCLES = 3 (prompts.py:6) vs the spec's stated 99 (spec.md:55,144,464,677,836). Register line 73: surfaced product decision — 3 is the sane operational cap; 99 would be pathologically expensive. Action = pick authoritative value and update the spec; do not blind-change code.
  • ⚠️ SURFACED DECISION (FR-013): deterministic pass is NOT wired. self_review_loop imports only SELF_REVIEW_PROMPT (review.py:15-19) and runs LLM-only review — it never calls run_deterministic_review. The CodeDirector's run_deterministic_review (review_checks.py:1264) has 0 real callers (the only "call sites" are docstring examples at review_checks.py:9-10 and verification/review/__init__.py:8-9); the parallel verification/review/engine.py:121 copy is also not called by QA (0 hits under qa/). So the 8 documented deterministic checks (SYNTAX/IMPORTS/ENTRY_POINT/LINE_LENGTH/FULL_IMPLEMENTATION/ DEPENDENCY_DECLARED/TRACEABILITY/LINT) run nowhere in the U:Cd path, contradicting US-004 AC-011/AC-012 (register line 74). (Note: Junior DOES run a DEPENDENCY_DECLARED-style check via validate_dependencies, so the capability is not wholly dead in the pipeline — just absent from U:Cd self-review.)
• Remaining work / plan:
  • Scope: decide (a) wire run_deterministic_review as the pre-LLM pass inside _run_review_cycle, OR (b) update spec to reflect intentional LLM-only review; and reconcile the cycles constant (3 vs 99).
  • Target files: codedirector/review.py (insert deterministic pass) + codedirector/prompts.py / specs/029-*/spec.md. Also consolidate the two run_deterministic_review definitions (codedirector-local vs verification/review) — the codedirector copy is the orphan.
  • Dependencies: verification/review subsystem (shared deterministic engine) — consolidation, not a point fix.
  • Effort: S (wire) or doc-only. Risk: low.
• Evidence log: refs run_deterministic_review → 2 def, 1 import, 0 use; refs MAX_SELF_REVIEW_CYCLES → value 3 at prompts.py:6; grep run_deterministic_review src/ → only docstring examples; Read review.py:1-130, prompts.py full, volk.py:82-99.

SPEC-030 Architect Volk — DONE (0700 confirmed; orphaned duplicates pending cleanup)

• 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 architect/volk.py:87-91.
  • FR-038/039/040/041 scaffold ✅ — _init_project creates 7 subdirs + context.json
    • git init + uv venv architect_project.py:22-57.
  • Security §Data Protection 0700 ✅ (the item to verify) — os.chmod(self.project_dir, 0o700) with OSError guard architect_project.py:34; register-remediated (line 37), tested per register.
  • US-006 UX integration ✅ — ux_design extracted volk.py:102; injected via _build_ux_section volk.py:325.
  • Mixin wiring ✅ — ArchitectProjectMixin imported from architect_project.py and used at volk.py:13,42 (refs ArchitectProjectMixin).
  • MAX_DESIGN_CYCLES: spec + architect_prompts.py both default 99 (consistent, unlike CodeDirector).
• ORPHANED duplicates (register line 79, confirmed):
  • architect/project_mixin.py — a second ArchitectProjectMixin definition (:19), 0 refs (only architect_project.py is imported).
  • architect/project_init.py — standalone init_project/write_design_docs/ parse_design/git_commit helpers, 0 imports anywhere in src/.
  • Plus context_mixin.py, context_builder.py, volk_context.py (register line 79). These are dead duplicates of the live architect_project.py / architect_context.py.
• Remaining work / plan: no functional gap. Cleanup: delete the orphaned duplicate modules (project_mixin.py, project_init.py, context_mixin.py, context_builder.py, volk_context.py) after confirming volk.py binds only the architect_* variants. Target files: those 5 modules. Dependencies: none. Effort S. Risk low (verify no test imports first).
• Evidence log: Read architect_project.py full; refs ArchitectProjectMixin → 2 def (architect_project.py used, project_mixin.py orphan); grep project_init|project_mixin import src/ → 0 imports; symbols project_init.py → 10 standalone functions, all uncalled externally.

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. Payload-carrier 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/030 deterministic review ↔ verification/review subsystem: two run_deterministic_review copies (codedirector-local orphan + verification/review engine); consolidation is a subsystem decision.

Related

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