docs(#344): Add CI verification to orchestrator guide

- Document CI configuration requirements
- Add CI verification step to execution loop
- Document auto-diagnosis categories and patterns
- Add CLI integration examples
- Add service integration code examples

Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>

docs/claude/orchestrator.md

@@ -86,23 +86,37 @@ See `docs/templates/README.md` for full documentation.
 
 ### CLI Tools
 
-Git operations use `@mosaic/cli-tools` package (auto-detects Gitea vs GitHub):
+Git and CI operations use `@mosaic/cli-tools` package:
 
 ```bash
-# Issue operations
+# Issue operations (auto-detects Gitea vs GitHub)
 pnpm exec mosaic-issue-create -t "Title" -b "Body" -m "Milestone"
 pnpm exec mosaic-issue-list -s open -m "Milestone"
 
-# PR operations
+# PR operations (auto-detects Gitea vs GitHub)
 pnpm exec mosaic-pr-create -t "Title" -b "Body" -B develop
 pnpm exec mosaic-pr-merge -n 42 -m squash -d
 
-# Milestone operations
+# Milestone operations (auto-detects Gitea vs GitHub)
 pnpm exec mosaic-milestone-create -t "M7-Feature" -d "Description"
+
+# CI/CD operations (Woodpecker)
+pnpm exec mosaic-ci-pipeline-status --latest
+pnpm exec mosaic-ci-pipeline-wait -n 42
+pnpm exec mosaic-ci-pipeline-logs -n 42
 ```
 
 See `packages/cli-tools/README.md` for full command reference.
 
+### CI Configuration
+
+Set these environment variables for Woodpecker CI integration:
+
+```bash
+export WOODPECKER_SERVER="https://ci.mosaicstack.dev"
+export WOODPECKER_TOKEN="your-token-here"  # Get from ci.mosaicstack.dev/user
+```
+
 ---
 
 ## Phase 1: Bootstrap
@@ -252,11 +266,17 @@ git push
 10. Update tasks.md: status=done/failed, completed_at={now}, used={actual}
 11. Cleanup reports: Remove processed report files
 12. Commit + push: git add docs/tasks.md && git commit && git push
-13. If phase verification task: Run phase retrospective
-14. Check context usage
-15. If >= 55%: Output COMPACTION REQUIRED checkpoint, STOP, wait for user
-16. If < 55%: Go to step 1
-17. After user runs /compact and says "continue": Go to step 1
+13. CI verification (if configured):
+    - Check latest pipeline status for the branch
+    - Wait for pipeline completion (timeout: 30min)
+    - On failure: Fetch logs and auto-diagnose
+    - Common failures: lint, type-check, test, build, security
+    - If CI fails: Mark task as failed, update tasks.md, restart from step 1
+14. If phase verification task: Run phase retrospective
+15. Check context usage
+16. If >= 55%: Output COMPACTION REQUIRED checkpoint, STOP, wait for user
+17. If < 55%: Go to step 1
+18. After user runs /compact and says "continue": Go to step 1
 ```
 
 ---
@@ -307,6 +327,105 @@ git push
 
 ---
 
+## CI Verification (Step 13)
+
+After pushing code, the orchestrator can optionally monitor CI pipeline status to catch failures early.
+
+### Configuration
+
+CI monitoring requires environment variables:
+
+```bash
+export WOODPECKER_SERVER="https://ci.mosaicstack.dev"
+export WOODPECKER_TOKEN="your-token-here"
+```
+
+If not configured, CI verification is skipped (orchestrator logs a warning).
+
+### Verification Process
+
+```
+1. After git push, get latest pipeline for the branch
+2. Wait for pipeline to complete (timeout: 30 minutes, configurable)
+3. Poll every 10 seconds (configurable)
+4. On completion:
+   - Success: Continue to next step
+   - Failure: Fetch logs and auto-diagnose
+```
+
+### Auto-Diagnosis
+
+When a pipeline fails, the orchestrator fetches logs and categorizes the failure:
+
+| Category   | Pattern                               | Suggestion                           |
+| ---------- | ------------------------------------- | ------------------------------------ |
+| Lint       | `eslint`, `lint.*error`               | Run `pnpm lint` locally              |
+| Type Check | `type.*error`, `tsc.*error`           | Run `pnpm typecheck` locally         |
+| Test       | `test.*fail`, `vitest.*fail`          | Run `pnpm test` locally              |
+| Build      | `build.*fail`, `compilation.*fail`    | Run `pnpm build` locally             |
+| Security   | `secret`, `security`, `vulnerability` | Review security scan, remove secrets |
+| Unknown    | (fallback)                            | Review full logs                     |
+
+### Failure Handling
+
+When CI fails:
+
+1. Log the failure category and diagnosis
+2. Update task status to `failed` in `tasks.md`
+3. Include diagnosis in task notes
+4. Commit the task update
+5. **Options:**
+   - Re-spawn worker with error context to fix
+   - Skip task and continue (if non-critical)
+   - Stop and alert (if critical blocker)
+
+### CLI Integration
+
+Use `@mosaic/cli-tools` for CI operations:
+
+```bash
+# Check latest pipeline status
+pnpm exec mosaic-ci-pipeline-status --latest
+
+# Wait for specific pipeline
+pnpm exec mosaic-ci-pipeline-wait -n 42 -t 1800
+
+# Get logs on failure
+pnpm exec mosaic-ci-pipeline-logs -n 42
+```
+
+### Service Integration
+
+The `CIOperationsService` (in `apps/orchestrator/src/ci/`) provides:
+
+- `getLatestPipeline(repo)` - Get most recent pipeline
+- `getPipeline(repo, number)` - Get specific pipeline
+- `waitForPipeline(repo, number, options)` - Wait with auto-diagnosis
+- `getPipelineLogs(repo, number)` - Fetch logs
+
+Example usage in orchestrator:
+
+```typescript
+// After git push
+const repo = "mosaic/stack";
+const pipeline = await ciService.getLatestPipeline(repo);
+
+if (pipeline) {
+  const result = await ciService.waitForPipeline(repo, pipeline.number, {
+    timeout: 1800,
+    fetchLogsOnFailure: true,
+  });
+
+  if (!result.success && result.diagnosis) {
+    this.logger.warn(`CI failed: ${result.diagnosis.category}`);
+    this.logger.warn(`Suggestion: ${result.diagnosis.suggestion}`);
+    // Handle failure...
+  }
+}
+```
+
+---
+
 ## Context Threshold Protocol (Orchestrator Replacement)
 
 **Threshold:** 55-60% context usage