upgrade-project

/upgrade-project — semantic-merge reconciliation for baseline files

You are reconciling files that create-baseline upgrade decided required semantic merge rather than mechanical merge. The CLI has already detected per-file customization, classified each file as tier 3 (SEMANTIC) at build time, and staged the three states (BASE / INCOMING / LOCAL) for you to reason about in main context. This skill is the only sanctioned way to drive that staged state to RECONCILED.

This skill is maintenance work, not a workflow phase. It is invoked reactively whenever the upgrade CLI prints the "run /upgrade-project to reconcile" pointer. It does not appear in .claude/state/workflow.json, does not require /triage, and does not trigger consent gates.

When to use

• The user just ran npx @friedbotstudio/create-baseline upgrade <target> and the CLI exited 5 with a "Pending semantic-merge stage at " message.
• The user types /upgrade-project or asks "reconcile the staged files".
• A previous /upgrade-project invocation hit a NEEDS_USER_INPUT fallback, the user provided direction, and you re-invoke to pick up where you left off.

Inputs (read from disk)

For each stage directory under .claude/state/upgrade/:

• manifest.json — the stage manifest the CLI wrote. Schema:

  {
    "stage_version": 1,
    "slug": "upgrade-flow-rework",
    "created_at": "2026-05-20T14:49:00.000Z",
    "baseline_version_from": "0.4.0",
    "baseline_version_to": "0.5.0",
    "files": [
      {
        "rel": "docs/init/seed.md",
        "base_sha256": "<hex>" | null,
        "incoming_sha256": "<hex>",
        "local_sha256": "<hex>",
        "status": "PENDING"
      }
    ]
  }
  

  base_sha256 is the per-entry classification discriminator: a 64-hex string means the CLI staged a recoverable BASE (three-way reconciliation); the JSON value null means BASE was unrecoverable when the user picked Merge on the tier-1 prompt (two-way reconciliation). See tier1-merge-option spec §Design pick 1A.
• For each entry, the staged artifacts are:
  • <rel>.baseline-incoming — the INCOMING content. Always present.
  • <rel>.baseline-base — the BASE content. Present iff base_sha256 is a string; absent for BASE-less entries.
  • The LOCAL file remains at its real path inside the target tree (untouched by the CLI).