Compozy QA Bootstrap

Provision infrastructure and scratch evidence for one QA pass. Bootstrap does not prove runtime behavior; downstream QA owns journeys and verdicts.

Required Inputs

• scenario-slug (optional): short lab context; defaults to release-candidate.
• --playbook : required when called by eng-real-scenario-qa; omitted for generic qa-execution infrastructure.
• --profile targeted --required-surface : use for a bounded non-agent journey; repeat the surface flag for every CLI/API/Web/runtime/provider plane in scope.

Procedure

Step 1: Create or Resume One Lab

1. Resolve the scenario slug and, for eng-real-scenario-qa, validate the playbook under .agents/skills/eng/eng-real-scenario-qa/references/playbooks/.
2. For a new pass, run the bootstrap helper (bootstrap, mutating): python3 .agents/skills/eng/eng-qa-bootstrap/scripts/bootstrap-qa-env.py --scenario "<scenario-slug>" --repo-root . [--playbook "<ref>" | --profile targeted --required-surface "<surface>"]
3. Reuse only when continuing the same active QA session or loop with its exact manifest: python3 .agents/skills/eng/eng-qa-bootstrap/scripts/bootstrap-qa-env.py --scenario "<scenario-slug>" --repo-root . [--playbook "<ref>"] --reuse-manifest "<manifest-path>"
4. Record the emitted BOOTSTRAP_MANIFEST; do not reconstruct environment values manually.

Done when: one fresh or same-session lab has one readable manifest and no unrelated lab was reused.

Step 2: Verify the Handoff Contract

1. Read .agents/skills/eng/eng-qa-bootstrap/references/bootstrap-contract.md in full.
2. Validate every required manifest field, env value, scratch-evidence file, provider-home policy, browser policy, audit command, and teardown command against that contract.
3. When a playbook was supplied, also validate the materialized playbook, agents, open-task tree, knowledge files, required deliverables/collaboration, and populated charter.
4. Treat scaffolding as empty evidence until downstream QA records real actions and the strict auditor passes.

Done when: manifest, env, paths, scenario contract, charter, playbook artifacts, and filesystem all describe the same isolated lab with no placeholders in a playbook run.

Step 3: Hand Off to Downstream QA

1. Pass qa-docs-path=docs/qa to qa-report and qa-execution; keep QA_OUTPUT_PATH as lab-side scratch evidence only.
2. Launch providers, Web, browser, and config operations exactly from the manifest contract. Preserve operator home for native_cli + home_policy=operator; use isolated provider homes for bound-secret or brokered lanes.
3. Export the manifest-derived COMPOZY_WEB_API_PROXY_TARGET for Web QA and serialize config writes against one isolated home.
4. Register every long-lived process immediately under <QA_OUTPUT_PATH>/qa/pids/.
5. Require downstream QA to run the manifest's strict AUDIT_COMMAND before a behavior-first verdict.

Done when: downstream skills consume the canonical manifest, durable findings land under docs/qa/, scratch evidence stays in the lab, and every owned process is registered.

Step 4: Preserve Continuation State

1. Report the manifest path, lab root, COMPOZY_HOME, base URL, dated run-report path, and reuse status.
2. For a continuing loop, append the exact machine-readable continuation block from the bootstrap contract.

Done when: the next continuation can identify the same lab from one exact manifest without discovery or guessing.

Step 5: Tear Down on Every Terminal Path

1. On PASS, FAIL, BLOCKED, or abort, run the manifest's exact TEARDOWN_COMMAND; only a confirmed continuation of the same loop may defer it.
2. The teardown must stop the daemon, tmux server, registered PIDs, lab-root processes, and lab-port listeners without touching unrelated labs.
3. Cite <QA_OUTPUT_PATH>/qa/teardown.json with "clean": true. Survivors are a blocking failure.
4. Reserve make qa-reap for intentional stale-lab recovery across the machine, not normal cleanup of one active run.

Done when: the current lab's teardown evidence is clean and no process owned by this pass remains alive.

Error Handling

• Requested reuse fails health checks: use the fresh manifest emitted by the helper; do not revive stale state manually.
• Provider reports global config errors: compare the command's home policy with the manifest; isolated and operator-home lanes intentionally differ.
• Web reaches the wrong daemon: restart the Web process with the manifest-derived proxy target.
• Teardown reports survivors: inspect each TEARDOWN_SURVIVOR, stop only processes owned by the current lab, and rerun the same targeted teardown.