# v1 to v2 Upgrade Guide

v2 is safer to regenerate than to migrate blindly. Keep your old state for reference, then rebuild the lifecycle reports with v2 commands.

## What you can usually keep

- your workspace source files
- checked-in project docs such as `AGENTS.md`, `CLAUDE.md`, `.cursor/rules/*`, or host-specific files after reviewing diffs
- manually approved host/global settings that were not generated by agent-harness
- old `mirror/raw/` material only as a cache/reference, not as proof of current trust

## What should be regenerated

Regenerate these unless you know they were produced by the current v2 contract:

- `discover/output/*`
- `mirror/index.jsonl`
- `mirror/bundles/*.lock.json`
- `install/**`
- `activate/**`
- `state/install/refresh-report.json`
- `state/install/refresh-state.json`
- `state/quarantine/quarantine-state.json`

Regeneration is safer because v2 adds stricter source verification, community scoring, quarantine lifecycle reports, asset fingerprints, Codex host metadata, and refresh policy tiers.

## Recommended first commands

From the workspace root:

```bash
agent-harness discover demand-profile
agent-harness discover sources
agent-harness discover sync
agent-harness discover catalog
agent-harness discover select --no-ai-enrich
agent-harness discover stats
agent-harness recommend report --intent general
agent-harness mirror plan
agent-harness mirror locks
agent-harness mirror diff
agent-harness install refresh --host <host>
agent-harness quarantine report
agent-harness wire <host>
```

Review reports before applying anything. `wire <host>` is a preview; use `wire <host> --apply` only after inspecting the target paths and notes.

## Detecting incompatible old artifacts

Treat artifacts as incompatible if:

- they lack `schemaVersion`
- validators fail during build/tests/commands
- refresh reports do not include policy tiers/counts
- quarantine reviews do not include evidence
- source packs do not declare `kind`, `hosts`, and `assetKinds`
- bundle locks reference assets missing from `mirror/index.jsonl`
- wire previews lack target paths or notes for the requested host

When in doubt, move the old state aside and regenerate:

```bash
mv .agent-harness .agent-harness-v1-backup
agent-harness discover demand-profile
```

On Windows PowerShell:

```powershell
Rename-Item .agent-harness .agent-harness-v1-backup
agent-harness discover demand-profile
```

## Changed behavior to expect

- Codex is a first-class host target.
- Community assets are scored and risky executable candidates are quarantined.
- Official sources can be demoted to `official-compatible` when ownership/publisher evidence is ambiguous.
- Refresh is policy-tiered: report-only, stage-only, low-risk apply, review-required, or blocked/quarantined.
- Executable/native assets can be staged, but host-native activation/install remains review-gated.
- Quarantine decisions are persisted with evidence and summarized in `state/quarantine/quarantine-state.json`.

## Reset and rollback

- Use `agent-harness wire <host> --reset` to remove adapter-managed project outputs.
- Use `agent-harness activate rollback --host <host> --generation <generation-id>` for activation rollback.
- Prefer keeping old `.agent-harness-v1-backup` until the v2 preview looks correct.
- Do not reuse old quarantine decisions unless the source URL, publisher, content hash, and executable behavior still match.

## Related docs

- [`V2-CONTRACT.md`](https://github.com/ar27111994/agent-harness/blob/main/docs/guides/V2-CONTRACT.md)
- [`HARNESS-MAINTENANCE-GUIDE.md`](https://github.com/ar27111994/agent-harness/blob/main/docs/guides/HARNESS-MAINTENANCE-GUIDE.md)
- [`QUARANTINE-PLAYBOOK.md`](https://github.com/ar27111994/agent-harness/blob/main/docs/playbooks/QUARANTINE-PLAYBOOK.md)
- [`CHANGELOG.md`](https://github.com/ar27111994/agent-harness/blob/main/CHANGELOG.md)