# ADR-010: Onboard Workflow with Checkpoint/Resume

**Status:** Accepted
**Date:** 2026-02

## Context

Onboarding an existing subrepo into the monorepo is a multi-step process that involves human interaction (renaming repos, merging PRs). The full flow is:

1. Prerequisites: rename existing repo, create new empty repo
2. Import: copy subrepo content into monorepo, create import PR(s)
3. Wait: human merges the import PR(s)
4. Reset: force-push josh-filtered history to the new empty repo
5. (Optional) Migrate open PRs from archived repo

Each step can fail or be interrupted. The process may span hours or days (waiting for PR review). If interrupted, restarting from scratch wastes work and can create duplicate PRs.

### Alternatives considered

1. **Single-shot script**: Run all steps in sequence. If interrupted, must restart from scratch. Duplicate PRs if import step is re-run.

2. **Manual step-by-step commands**: `import`, then manually run `reset`. Simple but error-prone — users may forget steps or run them out of order.

3. **Checkpoint/resume with persistent state**: Track the current step and intermediate results (PR numbers, reset branches) in persistent state. On re-run, resume from the last completed step.

## Decision

Implement `josh-sync onboard` as a checkpoint/resume workflow with state stored on the `josh-sync-state` branch at `<target>/onboard.json`.

### State machine

```
start → importing → waiting-for-merge → resetting → complete
```

Each transition is persisted before proceeding. Re-running `josh-sync onboard <target>` reads the current step and resumes.

### State schema

```json
{
  "step": "waiting-for-merge",
  "archived_api": "https://host/api/v1/repos/org/repo-archived",
  "archived_url": "git@host:org/repo-archived.git",
  "archived_auth": "ssh",
  "import_prs": { "main": 42 },
  "reset_branches": ["main"],
  "migrated_prs": [
    { "old_number": 5, "new_number": 12, "title": "Fix login" }
  ],
  "timestamp": "2026-02-10T14:30:00Z"
}
```

### Per-branch progress

Import and reset both iterate over branches. Progress is saved after each branch, so interruption mid-iteration resumes at the next unprocessed branch.

### PR migration

`josh-sync migrate-pr` is a separate command that reads onboard state (for the archived repo URL) and tracks migrated PRs. It uses `git apply --3way` for resilient patch application — the subrepo's content is identical after reset, so patches apply cleanly.

## Consequences

**Positive:**
- Safe to interrupt at any point — no duplicate work on resume
- Per-branch tracking prevents duplicate import PRs or redundant resets
- Archived repo URL stored in state — `migrate-pr` can operate independently
- `--restart` flag allows starting over if state is corrupted
- Human-friendly — prints instructions at each step

**Negative:**
- State management adds complexity (read/write onboard state, step validation)
- Interactive steps (`read -r`) are not suitable for fully automated pipelines
- Onboard state persists on the state branch even after completion (minor clutter)
- The step machine is linear — cannot skip steps or run them out of order