integrate

Select the blueprint

1. If the user named a blueprint file, use that file.
2. Otherwise, if this same conversation just finished a /tdd run and the TDD handoff named the blueprint it completed, reuse that file.
3. Otherwise ask the user which blueprint to verify, listing what is in docs/plans/. Never guess — /integrate takes exactly one blueprint.
4. If no blueprint exists, tell the user to run /blueprint first.

Read the ## Integration Test Requirements section from the selected blueprint (produced by /blueprint).

Integration passed checkboxes

• Every IT is executed on every run, even if its checkbox is already ticked — regress-all is the rule.
• Tick the Integration passed checkboxes only after a complete run in which every IT passes. If any IT fails, leave all checkboxes unchanged.
• On a code-logic failure, stop the app, run cleanup, report the actual vs expected difference, and do not tick any checkbox. Do not choose the next step for the user.

Data Setup & Cleanup

Pre-condition: Data Setup & Cleanup requires MCP database tools (describe_table, query, write). If the blueprint includes this section but MCP tools are unavailable, stop and report:

"Blueprint includes Data Setup & Cleanup but database MCP tools are unavailable. The blueprint cannot be verified in this environment. Either configure MCP or regenerate the blueprint without Data Setup (& Cleanup)."

Do not attempt CLI fallback. Do not skip silently.

If MCP is available and the blueprint includes a ## Data Setup & Cleanup section, run it before Integration Verification and clean up after, regardless of verification outcome (try-finally semantics).

Safety (SQL self-check)

Before executing any INSERT/UPDATE/DELETE via the database write tool:

1. UPDATE/DELETE must have a WHERE clause. If missing, stop and report.
2. The WHERE condition must filter by a unique key (PK or unique constraint). If the condition is not unique-guaranteed, stop and report.
3. INSERT must not reference a value that could change — no LIMIT 1 subqueries, no ORDER BY RAND(), no SELECT ... LIMIT 1.
4. If any check fails, stop and report. Do not attempt execution.

Setup (before application starts)

1. Generate a run-scoped RUN_ID (e.g. IT-YYYYMMDD-<sequence> or a UUID) and keep it for the whole run.
2. Read the setup description from the blueprint.
3. For each table declared in Setup, run describe_table to discover column names and data types.
4. Generate INSERT SQL that matches the description + the live schema, substituting {RUN_ID} with the generated value.
5. Execute via the database write MCP tool. If the data set exceeds the tool's per-statement row limit (e.g. 10 rows), split into multiple statements.
6. On failure: attempt cleanup for this RUN_ID (only rows this run may have inserted), then stop and report the error, the SQL attempted, and the actual DB error. Do not retry — let the user decide.

Cleanup (after all Integration Verification — always runs)

1. Read the cleanup description from the blueprint and substitute the same RUN_ID into every cleanup statement.
2. For each DELETE, pre-check with SELECT COUNT(*) first:
   • If count matches expectation (exactly 1 for a PK-based delete): run DELETE normally.
   • If count is 0: log a warning (nothing to clean up), skip.
   • If count is > expectation: log a warning (unexpected data), but still run DELETE — the WHERE condition is precise enough.
3. Execute DELETE SQL in FK-safe order via the database write tool. If the statement exceeds the tool's per-statement row limit (e.g. 10 rows), split into multiple statements.
4. On failure: report what wasn't cleaned up but do not block. The residue data is identifiable by the RUN_ID and can be cleaned up manually.

Execution

Lifecycle (strict ordering)

1. [Setup]      — if plan has Data Setup & Cleanup section, insert test data
2. Start app    — fresh start (kill existing first, see App lifecycle)
3. Verify       — run every integration command, record pass/fail
4. [Cleanup]    — if Setup was run, DELETE test data (regardless of verify outcome)
5. Stop app     — MANDATORY, regardless of verify outcome
6. Report       — pass/fail + cleanup status + app shutdown confirmed
7. Update blueprint — tick `Integration passed` checkboxes only if every IT passed; otherwise leave them unchanged

Step 5 is non-negotiable. It runs even if verification fails, even if the app fails to start. The only reason to skip it: the app was never started. Cleanup (step 4) runs whenever Setup (step 1) was executed — it is part of the same bracket. If there was no Data Setup section in the blueprint, skip both.

App lifecycle

Start (always fresh):

1. Check if the target port is already occupied. Use netstat -ano | findstr :<port> (Windows) or lsof -i :<port> / ss -tlnp | grep <port> (Linux/Mac).
2. If occupied, kill the existing process before starting. Track down the PID and kill it (taskkill /PID <pid> /F on Windows, kill <pid> elsewhere). If the process does not look like a previous run of this project (unknown name, unrelated service), report it and ask before killing.
3. Resolve the start command, in this order:
   • Verified facts from /setup-runtime: read docs/agents/runtime.md (the source of truth — if it exists, use its start command and profile).
   • Otherwise, discover from build files: pom.xml (Maven), build.gradle / build.gradle.kts (Gradle), docker-compose.yml (Docker), Makefile, package.json, etc.
     • Maven: mvn spring-boot:run (Windows pwsh: .\mvnw.cmd spring-boot:run)
     • Gradle: gradle bootRun (Windows pwsh: .\gradlew.bat bootRun)
     • Docker: docker-compose up -d
     • Others: infer from the project's build files
4. Record the process handle immediately after start. For JVM apps use jps -l; otherwise use the platform equivalent (Get-Process on Windows pwsh, pgrep on Unix) or the agent's background-job handle. Store it — you will need it to stop the app precisely. In DSH, prefer the background-job id and stop the app through the jobs API, with the PID as fallback.
5. Wait for the app to be ready. Poll the health endpoint or the first expected API until it responds. Use a default timeout of 300 seconds (5 minutes), overridable by READY_TIMEOUT in docs/agents/runtime.md. On timeout: stop the app and report "app not ready within N seconds". Do not proceed to verification until the app is reachable.

Stop (always, regardless of verification outcome):

1. Kill the process using the recorded handle: the background-job id in DSH, or the PID elsewhere.
2. Verify the port is free before reporting. If still occupied, kill the process tree explicitly (taskkill /PID <pid> /F /T on Windows, kill -9 <pid> elsewhere).
3. If the PID was lost (e.g. process crashed mid-verification), fall back to killing by port.

The start-stop bracket: every /integrate run starts a fresh app and kills it at the end. Never re-use a running instance — this ensures isolation between integration runs.

Verify loop

Redact secrets from all output: auth headers, tokens, passwords, PII. Show only the signal needed to diagnose.

1. Run every integration command from the blueprint, in order.
2. For each: assert actual result against expected result. Record pass/fail.
3. If any fail:
   • Diagnose: environment/config → fix directly. Code logic → stop and report the cause; do not change code.
   • Regress: re-run ALL commands, not just the failed one.
   • If same failure persists after 3 attempts, or a fix causes new failures: stop the app, run cleanup, then report and let the user decide.

Report

Only after the app is stopped and cleanup is complete:

Scope

• /integrate reads the blueprint's ## Integration Test Requirements section and may only edit the Integration passed checkboxes in that section. It does not edit slices or IT commands. It does not run module-level tests (those belong to /tdd).
• Modifications are limited to configuration, environment, and wiring (port, profile, classpath, dependency). If a logic change is needed to make an integration command pass, stop and report the cause; do not change code.

Handoff

Only after verification is complete AND the app is stopped (and cleanup done, if applicable), tell the user:

• All passed: "Integration verification complete. All commands pass. All Integration passed checkboxes ticked in the blueprint. Ready for PR."
• Some failed: "Integration verification failed: N/M commands passed. Failed: IT-x — expected ..., actual ... App stopped. Integration passed checkboxes unchanged."