| 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
- Read the legacy
.agents/skills/ai-qa-project/SKILL.md.
- 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.
- Create the canonical Skill. Preserve valid existing markers; otherwise wrap
the legacy body in one managed region and add one empty user region.
- Keep the legacy path and make it byte-identical to the canonical Skill.
- Run
ai-qa project-skill register --stdin-json with
{"host":"codex","path":".agents/skills/ai-qa-project/SKILL.md"}.
- Run
ai-qa project upgrade complete --migration project-format-v2-to-v3 --json.
- 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.
