feat(orchestrator): add Discuss Phase and PRD creation workflow (#1124)

* feat(orchestrator): add Discuss Phase and PRD creation workflow

- Introduce Discuss Phase for medium/complex objectives, generating context‑aware options and logging architectural decisions
- Add PRD creation step after discussion, storing the PRD in docs/prd.yaml
- Refactor Phase 1 to pass task clarifications to researchers
- Update Phase 2 planning to include multi‑plan selection for complex tasks and verification with gem‑reviewer
- Enhance Phase 3 execution loop with wave integration checks and conflict filtering

* feat(gem-team): bump version to 1.3.3 and refine description with Discuss Phase and PRD compliance verification

agents/gem-reviewer.agent.md

@@ -23,31 +23,56 @@ Security Auditing, OWASP Top 10, Secret Detection, PRD Compliance, Requirements
 </tools>
 
 <workflow>
-- Determine Scope: Use review_depth from task_definition.
-- Analyze: Read plan.yaml AND docs/prd.yaml (if exists). Validate task aligns with PRD decisions, state_machines, features, and errors. Identify scope with semantic_search. Prioritize security/logic/requirements for focus_area.
-- Execute (by depth):
-  - Full: OWASP Top 10, secrets/PII, code quality, logic verification, PRD compliance, performance
-  - Standard: Secrets, basic OWASP, code quality, logic verification, PRD compliance
-  - Lightweight: Syntax, naming, basic security (obvious secrets/hardcoded values), basic PRD alignment
-- Scan: Security audit via grep_search (Secrets/PII/SQLi/XSS) FIRST before semantic search for comprehensive coverage
-- Audit: Trace dependencies, verify logic against specification AND PRD compliance (including error codes).
-- Verify: Security audit, code quality, logic verification, PRD compliance per plan and error code consistency.
-- Determine Status: Critical=failed, non-critical=needs_revision, none=completed
-- Log Failure: If status=failed, write to docs/plan/{plan_id}/logs/{agent}_{task_id}_{timestamp}.yaml
-- Return JSON per <output_format_guide>
+- Determine Scope: Use review_scope from input. Route to plan review, wave review, or task review.
+- IF review_scope = plan:
+  - Analyze: Read plan.yaml AND docs/prd.yaml (if exists) AND research_findings_*.yaml.
+  - Check Coverage: Each phase requirement has ≥1 task mapped to it.
+  - Check Atomicity: Each task has estimated_lines ≤ 300.
+  - Check Dependencies: No circular deps, no hidden cross-wave deps, all dep IDs exist.
+  - Check Parallelism: Wave grouping maximizes parallel execution (wave_1_task_count reasonable).
+  - Check conflicts_with: Tasks with conflicts_with set are not scheduled in parallel.
+  - Check Completeness: All tasks have verification and acceptance_criteria.
+  - Check PRD Alignment: Tasks do not conflict with PRD features, state machines, decisions, error codes.
+  - Determine Status: Critical issues=failed, non-critical=needs_revision, none=completed
+  - Return JSON per <output_format_guide>
+- IF review_scope = wave:
+  - Analyze: Read plan.yaml, use wave_tasks (task_ids from orchestrator) to identify completed wave
+  - Run integration checks across all wave changes:
+    - Build: compile/build verification
+    - Lint: run linter across affected files
+    - Typecheck: run type checker
+    - Tests: run unit tests (if defined in task verifications)
+  - Report: per-check status (pass/fail), affected files, error summaries
+  - Determine Status: any check fails=failed, all pass=completed
+  - Return JSON per <output_format_guide>
+- IF review_scope = task:
+  - Analyze: Read plan.yaml AND docs/prd.yaml (if exists). Validate task aligns with PRD decisions, state_machines, features, and errors. Identify scope with semantic_search. Prioritize security/logic/requirements for focus_area.
+  - Execute (by depth):
+    - Full: OWASP Top 10, secrets/PII, code quality, logic verification, PRD compliance, performance
+    - Standard: Secrets, basic OWASP, code quality, logic verification, PRD compliance
+    - Lightweight: Syntax, naming, basic security (obvious secrets/hardcoded values), basic PRD alignment
+  - Scan: Security audit via grep_search (Secrets/PII/SQLi/XSS) FIRST before semantic search for comprehensive coverage
+  - Audit: Trace dependencies, verify logic against specification AND PRD compliance (including error codes).
+  - Verify: Security audit, code quality, logic verification, PRD compliance per plan and error code consistency.
+  - Determine Status: Critical=failed, non-critical=needs_revision, none=completed
+  - Log Failure: If status=failed, write to docs/plan/{plan_id}/logs/{agent}_{task_id}_{timestamp}.yaml
+  - Return JSON per <output_format_guide>
 </workflow>
 
 <input_format_guide>
 
 ```json
 {
-  "task_id": "string",
+  "review_scope": "plan | task | wave",
+  "task_id": "string (required for task scope)",
   "plan_id": "string",
-  "plan_path": "string", // "docs/plan/{plan_id}/plan.yaml"
-  "task_definition": "object", // Full task from plan.yaml (Includes: contracts, etc.)
-  "review_depth": "full|standard|lightweight",
+  "plan_path": "string",
+  "wave_tasks": "array of task_ids (required for wave scope)",
+  "task_definition": "object (required for task scope)",
+  "review_depth": "full|standard|lightweight (for task scope)",
   "review_security_sensitive": "boolean",
-  "review_criteria": "object"
+  "review_criteria": "object",
+  "task_clarifications": "array of {question, answer} (for plan scope)"
 }
 ```
 
@@ -89,7 +114,13 @@ Security Auditing, OWASP Top 10, Secret Detection, PRD Compliance, Requirements
         "location": "string",
         "prd_reference": "string"
       }
-    ]
+    ],
+    "wave_integration_checks": {
+      "build": { "status": "pass|fail", "errors": ["string"] },
+      "lint": { "status": "pass|fail", "errors": ["string"] },
+      "typecheck": { "status": "pass|fail", "errors": ["string"] },
+      "tests": { "status": "pass|fail", "errors": ["string"] }
+    }
   }
 }
 ```