stack/docs/CODEX-READY.md

# Codex Review — Ready to Commit

**Repository:** mosaic-stack (Mosaic Stack platform)
**Branch:** develop
**Date:** 2026-02-07

## Files Ready to Commit

```bash
cd ~/src/mosaic-stack
git status
```

**New files:**

- `.woodpecker/` — Complete Codex review CI pipeline
  - `codex-review.yml` — Pipeline configuration
  - `README.md` — Setup and troubleshooting guide
  - `schemas/code-review-schema.json` — Code review output schema
  - `schemas/security-review-schema.json` — Security review output schema
- `CODEX-SETUP.md` — Complete setup guide with activation steps

## What This Adds

### Independent AI Review System

- **Code quality review** — Correctness, testing, performance, code quality
- **Security review** — OWASP Top 10, secrets detection, injection flaws
- **Structured output** — JSON findings with severity levels
- **CI integration** — Automatic PR blocking on critical issues

### Works Alongside Existing CI

The main `.woodpecker.yml` handles:

- TypeScript type checking
- ESLint linting
- Vitest unit tests
- Playwright integration tests
- Docker builds

The new `.woodpecker/codex-review.yml` handles:

- AI-powered code review
- AI-powered security review

Both must pass for PR to be mergeable.

## Commit Command

```bash
cd ~/src/mosaic-stack

# Add Codex files
git add .woodpecker/ CODEX-SETUP.md

# Commit
git commit -m "feat: Add Codex AI review pipeline for automated code/security reviews

Add Woodpecker CI pipeline for independent AI-powered code quality and
security reviews on every pull request using OpenAI's Codex CLI.

Features:
- Code quality review (correctness, testing, performance, documentation)
- Security review (OWASP Top 10, secrets, injection, auth gaps)
- Parallel execution for fast feedback
- Fails on blockers or critical/high security findings
- Structured JSON output with actionable remediation steps

Integration:
- Runs independently from main CI pipeline
- Both must pass for PR merge
- Uses global scripts from ~/.claude/scripts/codex/

Files added:
- .woodpecker/codex-review.yml — Pipeline configuration
- .woodpecker/schemas/ — JSON schemas for structured output
- .woodpecker/README.md — Setup and troubleshooting
- CODEX-SETUP.md — Complete activation guide

To activate:
1. Add 'codex_api_key' secret to Woodpecker CI (ci.mosaicstack.dev)
2. Create a test PR to verify pipeline runs
3. Review findings in CI logs

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

# Push
git push
```

## Post-Push Actions

### 1. Add Woodpecker Secret

- Go to https://ci.mosaicstack.dev
- Navigate to `mosaic/stack` repository
- Settings → Secrets
- Add: `codex_api_key` = (your OpenAI API key)
- Select events: Pull Request, Manual

### 2. Test the Pipeline

```bash
# Create test branch
git checkout -b test/codex-review
echo "# Test change" >> README.md
git add README.md
git commit -m "test: Trigger Codex review"
git push -u origin test/codex-review

# Create PR (using tea CLI for Gitea)
tea pr create --title "Test: Codex Review Pipeline" \
              --body "Testing automated AI code and security reviews"
```

### 3. Verify Pipeline Runs

- Check CI at https://ci.mosaicstack.dev
- Look for `code-review` and `security-review` steps
- Verify structured findings in logs
- Test that critical/high findings block merge

## Local Testing (Optional)

Before pushing, test locally:

```bash
cd ~/src/mosaic-stack

# Review uncommitted changes
~/.claude/scripts/codex/codex-code-review.sh --uncommitted

# Review against develop
~/.claude/scripts/codex/codex-code-review.sh -b develop
```

## Already Tested

✅ **Tested on calibr repo commit `fab30ec`:**

- Successfully identified merge-blocking lint regression
- Correctly categorized as blocker severity
- Provided actionable remediation steps
- High confidence (0.98)

This validates the entire Codex review system.

## Benefits

✅ **Independent review** — Separate AI model from Claude sessions
✅ **Security-first** — OWASP coverage + CWE IDs
✅ **Actionable** — Specific file/line references with fixes
✅ **Fast** — 15-60 seconds per review
✅ **Fail-safe** — Blocks merges on critical issues
✅ **Reusable** — Global scripts work across all repos

## Documentation

- **Setup guide:** `CODEX-SETUP.md` (this repo)
- **Pipeline README:** `.woodpecker/README.md` (this repo)
- **Global scripts:** `~/.claude/scripts/codex/README.md`
- **Test results:** `~/src/calibr/TEST-RESULTS.md` (calibr repo test)

## Next Repository

After mosaic-stack, the Codex review system can be added to:

- Any repository with Woodpecker CI
- Any repository with GitHub Actions (using `openai/codex-action`)
- Local-only usage via the global scripts

Just copy `.woodpecker/` directory and add the API key secret.

---

_Ready to commit and activate! 🚀_