Systematic Project QA

Required Inputs

• qa-output-path (optional): Directory where QA artifacts (issues, screenshots, verification reports) are stored. When provided, create the directory if it does not exist and use it for all QA outputs. When omitted, fall back to repository conventions or /tmp/codex-qa-<slug>.

Procedures

Step 1: Discover the Repository QA Contract

1. Read root instructions, repository docs, and CI/build files before running commands.
2. Execute python3 scripts/discover-project-contract.py --root . to surface candidate install, verify, build, test, lint, start commands, Web UI signals, and E2E signals.
3. Read references/project-signals.md when command ownership is ambiguous or when multiple ecosystems are present.
4. Read references/e2e-coverage.md to decide whether the repository already supports public-surface automated coverage and how strong that support is.
5. Prefer repository-defined umbrella commands such as make verify, just verify, or CI entrypoints over language-default commands.
6. Identify the changed surface and the regression-critical surface before choosing scenarios.
7. Determine whether the project has a Web UI surface. Indicators include: a start or dev command that launches a web server, framework config files (next.config.*, vite.config.*, nuxt.config.*, angular.json, svelte.config.*), or HTML/template entry points. Record the dev server URL (default http://localhost:3000 unless the project specifies otherwise).
8. Record the E2E contract in working notes: support detected or not, harness name, canonical command, known spec locations, and blockers.
9. Resolve the QA artifact directory. If the user provided a qa-output-path argument, use that path. Otherwise, use repository conventions. If neither exists, fall back to /tmp/codex-qa-<slug>. Create the qa/ subdirectory under the resolved path if it does not exist. Store all issues, screenshots, and verification reports under <qa-output-path>/qa/.