project-format-v2-to-v3

name	project-format-v2-to-v3
description	Migrate an AI QA project from legacy project format v2 to canonical Project Skill format v3. Use only when ai-qa project upgrade check returns migration project-format-v2-to-v3.

Migrate Project Format v2 to v3

Intent

Make one project-owned canonical Project Skill serve every host while retaining the existing Codex path as a registered rendering.

Preserve

• Preserve the legacy procedure and user content.
• Do not modify runs, run groups, evidence, reports, receipts, cases, or unrelated worktree paths.
• Do not introduce literal secrets.

Normal path

1. Read the legacy .agents/skills/ai-qa-project/SKILL.md.
2. Run ai-qa project upgrade begin --stdin-json with the legacy path, .ai-qa/project-skill/SKILL.md, and .ai-qa/project-skill/renderings.yaml.
3. Create the canonical Skill. Preserve valid existing markers; otherwise wrap the legacy body in one managed region and add one empty user region.
4. Keep the legacy path and make it byte-identical to the canonical Skill.
5. Run ai-qa project-skill register --stdin-json with {"host":"codex","path":".agents/skills/ai-qa-project/SKILL.md"}.
6. Run ai-qa project upgrade complete --migration project-format-v2-to-v3 --json.
7. Continue only when completion reports project format 3.

Do not ask whether to delete the legacy path. Retention is the migration default.

Recovery

History-writing commands are unavailable while project migration recovery is active. Inspect every declared target, the ledger, and all validation invariants. Complete only when every invariant holds; otherwise abort.

• If the invariants already hold, retry ai-qa project upgrade complete --migration project-format-v2-to-v3 --json.
• If any invariant does not hold, run ai-qa project upgrade abort --migration project-format-v2-to-v3 --json. Abort restores the declared targets and CLI-owned project state while preserving undeclared config edits.

After abort, rerun ai-qa project upgrade check --stdin-json with an absolute host context such as {"host":"codex","agentsHome":"/Users/example/.agents"}, execute the returned migration again, and run doctor only after check returns up_to_date. Stop with the original data preserved if complete or abort reports a conflict.