Merge pull request #253 from zoidbergclawd/feature/agent-quality-sprint

Agent output quality + game framework bundling

Author: zoidbergclawd

ARCHITECTURE.md

@@ -84,27 +84,32 @@ Planning Mode (conversational specification assistant):
    a. AUTO-TEST: autoMatchTests() auto-generates behavioral tests for when_then
                  requirements missing test_id (Explorer level only; no-op at Builder/Architect)
    b. PLAN:     MetaPlanner calls Claude API to decompose spec into task DAG
-   c. MEETINGS: evaluateAndInvite('plan_ready') checks meeting triggers
+                MetaPlanner auto-selects game framework (Phaser/p5/Three.js) if not specified
+                Multi-file task planning enforced: each task owns one file, no concurrent edits
+   c. FRAMEWORK: Copy selected framework lib to workspace lib/ (if applicable)
+   d. MEETINGS: evaluateAndInvite('plan_ready') checks meeting triggers
                 (currently no meetings fire at plan_ready; all moved to per-task/deploy events)
-   d. TRACE:    Build traceability map from spec requirements <-> behavioral tests
-   e. PORTALS:  Initialize MCP/CLI portal adapters if spec declares portals
-   f. EXECUTE:  Streaming-parallel pool (Promise.race, up to 3 concurrent tasks)
-                Each agent gets: role prompt + task description + context from prior tasks
+   e. TRACE:    Build traceability map from spec requirements <-> behavioral tests
+   f. PORTALS:  Initialize MCP/CLI portal adapters if spec declares portals
+   g. EXECUTE:  Streaming-parallel pool (Promise.race, up to 3 concurrent tasks)
+                Each agent gets: role prompt + framework context + task description + context from prior tasks
                 Agent output streams via SDK -> WebSocket events to frontend
                 Git commit after each completed task (serialized via mutex)
                 Token budget tracked per agent; warning at 80%, halt on exceed
                 Per-task meeting triggers: design review (task_starting), mid-build
                   meetings at 25%/50%/60% completion (task_completed)
-   g. TEST:    TestRunner executes pytest/node, parses results + coverage
+   h. TEST:    TestRunner executes pytest/node, parses results + coverage
                Traceability tracker updates requirement-test status
-   h. HEALTH:  HealthTracker computes score (0-100) and grade (A-F)
+   i. GATE:    Test pass rate gate -- auto-fix if below threshold
+               (explorer: no gate, builder: 50%/1 fix, architect: 80%/2 fixes)
+   j. HEALTH:  HealthTracker computes score (0-100) and grade (A-F)
                HealthHistoryService persists trend data for Architect level
-   i. DEPLOY:  Surface before_deploy rules as deploy_checklist event
+   k. DEPLOY:  Surface before_deploy rules as deploy_checklist event
                evaluateAndInvite('deploy_started') for device/web deploy meetings
                If web: build -> find serve dir -> start local HTTP server -> open browser
                If devices: resolveDeployOrder -> flash wizard per device
                If CLI portals: execute via CliPortalAdapter (no shell)
-   j. COMPLETE: evaluateAndInvite('session_complete') -> Architecture agent meeting
+   l. COMPLETE: evaluateAndInvite('session_complete') -> Architecture agent meeting
 5. session_complete event with summary
 6. Post-build actions (optional):
    - FIX: POST /api/sessions/:id/fix with bugReport -> Orchestrator.runFix()
@@ -158,7 +163,7 @@ In dev mode, Vite (port 5173) proxies `/api/*` and `/ws/*` to backend (port 8000
 ## Core Abstractions
 
 ### NuggetSpec
-JSON schema produced by blockInterpreter from Blockly workspace. Drives the entire pipeline. Contains: goal, requirements (with test traceability), style, agents, deployment target, workflow flags (feedback loops, system level, behavioral tests), skills, rules, portals, devices, runtime config (agent name, voice, greeting), knowledge (backpack sources, study mode), composition (provides/requires interfaces for Spec Graph).
+JSON schema produced by blockInterpreter from Blockly workspace. Drives the entire pipeline. Contains: goal, requirements (with test traceability), style, agents, deployment target, workflow flags (feedback loops, system level, behavioral tests), skills, rules, portals, devices, runtime config (agent name, voice, greeting), knowledge (backpack sources, study mode), composition (provides/requires interfaces for Spec Graph), framework (optional: phaser/p5/threejs/none -- auto-selected by MetaPlanner if not set).
 
 ### Task DAG
 Directed acyclic graph of tasks with dependencies. Generated by MetaPlanner. Executed in topological order by Orchestrator. Uses Kahn's algorithm (`utils/dag.ts`).

backend/CLAUDE.md

@@ -104,6 +104,7 @@ src/
     planningAgent.ts     System prompt for Planning Mode conversational agent
     metaPlanner.ts       System prompt for task decomposition
     builderAgent.ts      Builder role prompt template
+    frameworks.ts        Framework-specific prompt context (Phaser, p5.js, Three.js): multi-file architecture rules, API patterns, MetaPlanner task planning with per-framework decomposition (scenes/modules/components)
     testerAgent.ts       Tester role prompt template
     reviewerAgent.ts     Reviewer role prompt template
     teaching.ts          Teaching moment curriculum and templates
@@ -121,6 +122,7 @@ src/
     pathValidator.ts     Workspace path validation (blocklist for system/sensitive dirs)
     safeEnv.ts           Sanitized process.env copy (strips ANTHROPIC_API_KEY)
     findFreePort.ts      Scans for available TCP port from a starting port
+    frameworkLoader.ts   Copies selected game framework (Phaser/p5/Three.js) from bundled resources to nugget workspace lib/
     anthropicClient.ts   Singleton factory for the Anthropic SDK client
 ```
 
@@ -139,6 +141,7 @@ src/
 | POST | /api/sessions/:id/planning/generate | Generate canvas blocks from plan |
 | GET | /api/sessions/:id/planning | Get current planning state |
 | POST | /api/sessions/:id/fix | Targeted bug fix (requires session in 'done' state, body: bugReport + failingTests) |
+| POST | /api/sessions/:id/screenshot | Visual smoke test (body: { base64 }, returns { passed, summary, issues }) |
 | POST | /api/sessions/:id/launch | Serve built nugget without rebuild (finds index.html, spawns local server, returns URL) |
 | POST | /api/sessions/:id/gate | Human gate response |
 | POST | /api/sessions/:id/question | Answer agent question |
@@ -195,7 +198,7 @@ src/
 | GET | /api/spec-graph/:id/interfaces | Resolve interface contracts among nodes |
 
 ### WebSocket Events (server -> client)
-`planning_started`, `plan_ready`, `planning_mode_started`, `planning_turn`, `planning_question`, `planning_plan_updated`, `planning_ready`, `planning_canvas_generated`, `planning_teaching`, `planning_learning_summary`, `planning_error`, `task_started`, `task_completed`, `task_failed`, `agent_output`, `commit_created`, `token_usage`, `budget_warning`, `test_expectations` (task_id, tests[] with name/description -- pre-generated pending tests), `test_result`, `test_phase_complete` (passed, failed, total -- emitted after all `test_result` events), `coverage_update`, `deploy_started`, `deploy_progress`, `deploy_checklist`, `deploy_complete` (includes `url?` for web deploys), `serial_data`, `human_gate`, `user_question`, `skill_*`, `teaching_moment`, `narrator_message`, `permission_auto_resolved`, `minion_state_change`, `workspace_created`, `flash_prompt`, `flash_progress`, `flash_complete`, `context_flow` (from_task_id, to_task_ids, summary_preview), `documentation_ready`, `meeting_invite`, `meeting_started`, `meeting_message`, `meeting_canvas_update`, `meeting_outcome`, `meeting_ended`, `traceability_update`, `traceability_summary`, `correction_cycle_started`, `correction_cycle_progress`, `convergence_update`, `composition_started` (graph_id, node_ids), `composition_impact` (graph_id, changed_node_id, affected_nodes, severity), `decomposition_narrated`, `impact_estimate`, `boundary_analysis`, `system_health_update`, `system_health_summary`, `health_history` (entries array for Architect trend tracking), `fix_started` (bugReport), `fix_task_completed` (taskId, success), `fix_tests_completed` (passed, failed, total), `meeting_blocking_task` (task_id, meeting_type_id), `meeting_unblocking_task` (task_id), `error`, `session_complete`
+`planning_started`, `plan_ready`, `planning_mode_started`, `planning_turn`, `planning_question`, `planning_plan_updated`, `planning_ready`, `planning_canvas_generated`, `planning_teaching`, `planning_learning_summary`, `planning_error`, `task_started`, `task_completed`, `task_failed`, `agent_output`, `commit_created`, `token_usage`, `budget_warning`, `test_expectations` (task_id, tests[] with name/description -- pre-generated pending tests), `test_result`, `test_phase_complete` (passed, failed, total -- emitted after all `test_result` events), `coverage_update`, `deploy_started`, `deploy_progress`, `deploy_checklist`, `deploy_complete` (includes `url?` for web deploys), `serial_data`, `human_gate`, `user_question`, `skill_*`, `teaching_moment`, `narrator_message`, `permission_auto_resolved`, `minion_state_change`, `workspace_created`, `flash_prompt`, `flash_progress`, `flash_complete`, `context_flow` (from_task_id, to_task_ids, summary_preview), `documentation_ready`, `meeting_invite`, `meeting_started`, `meeting_message`, `meeting_canvas_update`, `meeting_outcome`, `meeting_ended`, `traceability_update`, `traceability_summary`, `correction_cycle_started`, `correction_cycle_progress`, `convergence_update`, `composition_started` (graph_id, node_ids), `composition_impact` (graph_id, changed_node_id, affected_nodes, severity), `decomposition_narrated`, `impact_estimate`, `boundary_analysis`, `system_health_update`, `system_health_summary`, `health_history` (entries array for Architect trend tracking), `auto_fix_started` (passRate, threshold, attempt), `visual_smoke_test` (passed, summary, issues[]), `fix_started` (bugReport, isAutoFix?), `fix_task_completed` (taskId, success), `fix_tests_completed` (passed, failed, total), `meeting_blocking_task` (task_id, meeting_type_id), `meeting_unblocking_task` (task_id), `error`, `session_complete`
 
 ### Agent Runtime WebSocket Events (/v1/agents/:id/stream)
 Client sends `turn` (text) or `audio_turn` (audio) messages. Server responds with:
@@ -208,7 +211,7 @@ Client sends `turn` (text) or `audio_turn` (audio) messages. Server responds wit
 
 - **Session state**: In-memory Maps with optional JSON persistence for checkpoint/recovery. Cleanup timer (5 min) starts on WS connect; cancelled at build start, re-armed in `.finally()` after build completes. Meeting activity (accept, message, end), kid-initiated meeting starts, and fix/launch requests also reset the timer. `impactEstimate` and `boundaryAnalysis` persisted on session during plan phase for Blueprint meeting context.
 - **NuggetSpec validation**: Zod schema validates at `/api/sessions/:id/start` (string caps, array limits, portal command allowlist).
-- **SDK query per task**: Each agent task calls `query()` from `@anthropic-ai/claude-agent-sdk` with `permissionMode: 'bypassPermissions'` and explicit `pathToClaudeCodeExecutable` (resolved once at module load by `agentRunner.ts`). The SDK uses system `node` to spawn `cli.js`. Node.js is a prerequisite; Electron main process shows a dialog prompting install if missing. Default `maxTurns=25` (`MAX_TURNS_DEFAULT`). On retry, grants 10 additional turns per attempt (`MAX_TURNS_RETRY_INCREMENT`), so retries progress: 25 → 35 → 45.
+- **SDK query per task**: Each agent task calls `query()` from `@anthropic-ai/claude-agent-sdk` with `permissionMode: 'bypassPermissions'` and explicit `pathToClaudeCodeExecutable` (resolved once at module load by `agentRunner.ts`). The SDK uses system `node` to spawn `cli.js`. Node.js is a prerequisite; Electron main process shows a dialog prompting install if missing. Default `maxTurns=25` (`MAX_TURNS_DEFAULT`). On retry, grants 10 additional turns per attempt (`MAX_TURNS_RETRY_INCREMENT`), so retries progress: 25 → 35 → 45. Builder agents are instructed to self-verify by running `node tests/test_{task_id}.js` before writing their summary.
 - **API key propagation**: `POST /api/internal/config` sets `process.env.ANTHROPIC_API_KEY` then calls `resetAnthropicClient()` to invalidate the singleton. Module-level services (`meetingAgentService`, `planningService`) call `getAnthropicClient()` per-use (no cached `this.client`) so key changes propagate immediately.
 - **Stale metadata cleanup**: On each build, `setupWorkspace()` removes `.elisa/{comms,context,status}` from previous sessions before recreating them. Preserves `.elisa/logs/`, source files, and `.git/`.
 - **Structural digest injection**: Agent task prompts include function/class signatures extracted from workspace source files (via `ContextManager.buildStructuralDigest()`), allowing agents to orient without reading each file.
@@ -218,6 +221,7 @@ Client sends `turn` (text) or `audio_turn` (audio) messages. Server responds wit
 - **Context chain**: After each task, summary + structural digest written to `.elisa/context/nugget_context.md`.
 - **Cancellation**: `Orchestrator.cancel()` via AbortController; signal propagated to Agent SDK `query()` calls. Session state set to `done` on error.
 - **Content safety**: All agent prompts enforce age-appropriate output (8-14). Placeholder values sanitized before interpolation (`sanitizePlaceholder()`).
+- **Game frameworks**: Phaser 3, p5.js, Three.js bundled in `build/frameworks/` (downloaded by `scripts/bundle-frameworks.mjs`). MetaPlanner auto-selects or kid picks via Goal block dropdown. Selected library copied to workspace `lib/` after planning. Multi-file architecture enforced: scaffold creates all files as stubs, each feature task owns one module file, no concurrent edits to same file.
 - **Flash mutex**: `HardwareService.flash()` serializes concurrent calls via Promise-chain mutex.
 - **WebSocket heartbeat + send queue**: Server sends protocol-level pings every 30s (`WS_PING_INTERVAL_MS`). Connections that miss a pong are terminated via `ws.terminate()`. All `sendEvent()` calls are serialized through a per-session FIFO queue with `setImmediate` yield between each frame, preventing burst-flooding the Vite proxy even when concurrent fire-and-forget callers (agent_output streaming, meeting triggers) overlap. Queue depth warnings at 10/50/100; drain summaries logged for batches >5. `wsAlive` WeakMap tracks per-connection liveness.
 - **Graceful shutdown**: SIGTERM/SIGINT handlers cancel orchestrators, close WS server, 10s force-exit. `SessionStore.onCleanup` invokes `ConnectionManager.cleanup()` for WS teardown.

backend/src/models/session.ts

@@ -43,6 +43,7 @@ export interface MetaPlannerPlan {
   tasks: Task[];
   agents: Agent[];
   plan_explanation?: string;
+  framework?: string;
 }
 
 export interface BuildSession {
@@ -58,6 +59,7 @@ export interface BuildSession {
   impactEstimate?: { estimated_tasks: number; complexity: string; heaviest_requirements: string[] };
   boundaryAnalysis?: { inputs: Array<{ name: string; type: string; source?: string }>; outputs: Array<{ name: string; type: string; source?: string }>; boundary_portals: string[] };
   planningSession?: PlanningSession;
+  testGatePassed?: boolean;
 }
 
 export interface AgentResult {

backend/src/prompts/builderAgent.test.ts

@@ -38,9 +38,11 @@ describe('builderAgent SYSTEM_PROMPT', () => {
     expect(SYSTEM_PROMPT).toContain('BUILDER');
   });
 
-  it('contains Thinking Steps section', () => {
+  it('contains Thinking Steps section with self-verification', () => {
     expect(SYSTEM_PROMPT).toContain('## Thinking Steps');
     expect(SYSTEM_PROMPT).toContain('file manifest and structural digest');
+    expect(SYSTEM_PROMPT).toContain('Run your tests');
+    expect(SYSTEM_PROMPT).toContain('node tests/test_{task_id}.js');
   });
 
   it('contains Turn Efficiency section', () => {
@@ -56,6 +58,19 @@ describe('builderAgent SYSTEM_PROMPT', () => {
   it('contains wind-down instruction referencing turn limit', () => {
     expect(SYSTEM_PROMPT).toContain('wind down');
   });
+
+  it('requires running test file before summary', () => {
+    expect(SYSTEM_PROMPT).toContain('MUST run');
+    expect(SYSTEM_PROMPT).toContain('tests/test_{task_id}.js');
+  });
+
+  it('instructs agents not to leave FAIL stubs', () => {
+    expect(SYSTEM_PROMPT).toContain('do NOT leave FAIL stubs');
+  });
+
+  it('instructs honesty when node is unavailable', () => {
+    expect(SYSTEM_PROMPT).toContain('do not claim manual verification');
+  });
 });
 
 describe('formatStyle', () => {
@@ -99,8 +114,12 @@ describe('formatTaskPrompt', () => {
     role: 'builder',
     persona: 'A friendly robot',
     task: {
+      id: 'task-1',
       name: 'Build UI',
       description: 'Create the main UI',
+      status: 'pending' as const,
+      agent_name: 'Builder Bot',
+      dependencies: [],
       acceptance_criteria: ['Page renders', 'Button works'],
     },
     spec: {
@@ -126,15 +145,15 @@ describe('formatTaskPrompt', () => {
   it('omits acceptance criteria section when empty array', () => {
     const result = formatTaskPrompt({
       ...baseParams,
-      task: { name: 'Test', description: 'Desc', acceptance_criteria: [] },
+      task: { ...baseParams.task, name: 'Test', description: 'Desc', acceptance_criteria: [] },
     });
     expect(result).not.toContain('Acceptance Criteria');
   });
 
   it('omits acceptance criteria section when undefined', () => {
     const result = formatTaskPrompt({
       ...baseParams,
-      task: { name: 'Test', description: 'Desc' },
+      task: { ...baseParams.task, name: 'Test', description: 'Desc', acceptance_criteria: undefined as any },
     });
     expect(result).not.toContain('Acceptance Criteria');
   });
@@ -423,6 +442,12 @@ describe('formatTaskPrompt', () => {
     expect(result).not.toContain('## Available Portals');
   });
 
+  it('includes test file path in user prompt', () => {
+    const result = formatTaskPrompt(baseParams);
+    expect(result).toContain('## Your Test File');
+    expect(result).toContain('node tests/test_task-1.js');
+  });
+
   it('includes multiple portals', () => {
     const result = formatTaskPrompt({
       ...baseParams,

backend/src/prompts/builderAgent.ts

@@ -36,7 +36,9 @@ relative to cwd automatically. Do not reference paths outside this workspace.
 1. Scan the file manifest and structural digest below to understand what exists. Only Read specific files when you need implementation details not visible in signatures.
 2. Plan your changes: identify which files to create or modify and how they fit together.
 3. Implement the task, writing or editing files one at a time.
-4. Verify your work: re-read changed files to confirm correctness, then write your summary.
+4. Run your tests: execute \`node tests/test_{task_id}.js\` and check the output.
+5. Fix any FAIL lines -- update your code or fix the test assertions. Re-run until all PASS.
+6. Write your summary to .elisa/comms/{task_id}_summary.md.
 
 ## Turn Efficiency
 You have a limited turn budget of {max_turns} turns. Prioritize implementation over exploration:
@@ -53,6 +55,10 @@ Rules:
 - Output format: console.log('PASS: test_name') or console.log('FAIL: test_name')
 - Do not delete test files or remove test entries
 - Write assertions that genuinely verify the acceptance criteria
+- After implementing, you MUST run \`node tests/test_{task_id}.js\` before writing your summary
+- If a test requires browser APIs (DOM, canvas), convert it to a Node.js-compatible check \
+(file existence, string matching, syntax validation) -- do NOT leave FAIL stubs
+- If node is unavailable, state this clearly in your summary -- do not claim manual verification
 
 ## Rules
 - Write clean, well-structured code appropriate for the nugget type.
@@ -108,6 +114,10 @@ export function formatTaskPrompt(params: {
     }
   }
 
+  if (task.id) {
+    parts.push(`\n## Your Test File\nRun before finishing: node tests/test_${task.id}.js`);
+  }
+
   const nugget = spec.nugget ?? {};
   parts.push(`\n## Nugget Context\nGoal: ${nugget.goal ?? 'Not specified'}`);
   if (nugget.description) {