update-qm

Determine whether this is a source fork or a package deployment before choosing the update procedure. Source forks may intentionally change core; preserve those changes. Contributing them upstream is optional.

Identify the checkout

Run git remote -v and inspect the files and ancestry. If origin is yc-software/qm, this is upstream itself, not a downstream sync target. A different origin alone does not prove a source fork. A source fork has the QM source tree and shared upstream history; a package deployment has a deployment config and a pinned @yc-software/qm dependency. In a source fork with nested deployment directories, update source unless the request specifically targets a nested package pin.

For a package deployment, work on a topic branch and install the requested release with npm install --save-exact @yc-software/qm@<version>. If no version is specified, resolve the current published release first. Review the package and lockfile diff, contract changes, and image overrides that could keep workloads on older images. Package updates do not refresh generated runbooks, skills, or vendored Terraform: compare the release's scaffold in a separate temporary directory and reconcile required changes without reinitializing or overwriting the existing deployment. Run the installed CLI's check, doctor, and plan, then open a PR in the deployment repository. Deploy only within the user's requested scope, following its deployment runbook and live checks. Do not add an upstream source remote or merge source into a package deployment.

For a source fork, check the upstream remote points to yc-software/qm; if absent, add git remote add upstream git@github.com:yc-software/qm. Confirm shared history before merging. Never merge downstream history into upstream. Use --repo on every gh command. Inspect the actual default branch; the examples below assume main and must be adapted if the fork deliberately uses another name. If a mirror-seeded repository has a stale feature branch as its default, identify the intended base before syncing; do not silently merge into the stale branch or delete existing refs.

Merge, never rebase

origin/main is published history that deploys and other clones track. Rebasing it onto upstream rewrites those commits, so always merge.

git switch main
git pull --ff-only origin main
git fetch upstream
git switch -c codex/sync-upstream-<yyyy-mm-dd>
git log --oneline main..upstream/main
git merge upstream/main

Record the commit range before resolving anything so the PR can state it. If the merge reports "Already up to date", delete the branch and report that instead of opening an empty PR.

Resolving conflicts

Read both sides and the local commits that explain the customization. Preserve intentional local behavior while integrating upstream fixes; a core conflict is expected maintenance, not a policy violation. Keep deployment data in the layer or separate private deployment repository where practical. Do not discard a core modification just because it is organization-specific or insist it be contributed upstream.

Document conflicts, resolutions, and remaining divergence in the sync PR. When intent cannot be recovered from code, tests, or history, ask the operator before choosing a behavior. Review inherited CI and publishing changes for the fork's own accounts and registries rather than enabling upstream workflows blindly.

Verify before opening the PR

Determine affected tests from the merged range and conflict resolutions. Run those locally plus typecheck and lint; include CLI tests for CLI or deployment-contract changes. Use the full local suite only when the affected scope cannot be determined; otherwise let CI run it. Install the locked dependencies first:

npm ci
npm run typecheck
npm run lint

A sync can raise the deployment contract major, and the CLI rejects a layer config written for the old one. Check each organization layer with the in-tree CLI (npm exec qm does not work in a source checkout; the workspace symlink points at cli/, which is unbuilt):

node cli/bin/qm.ts check --config deploy/layers/<org>/qm.config.jsonc

For deployments outside the checkout, substitute their config paths. If a config reports an unsupported contract major, adapting it is part of the sync. Verify non-trivial behavior changes in a live dev instance before opening the PR, per AGENTS.md. Production service builds must use --build-from against this checkout (or deliberately published custom images); merging source does not update published runtime images. See the README source deployment procedure.

Open the PR

git push -u origin codex/sync-upstream-<yyyy-mm-dd>
gh pr create --repo <source-fork> --base main \
  --title "Sync upstream qm through <short-sha>" \
  --body-file .generated/sync-body.md

Pass --repo to every gh command you run in a private fork. Without it, gh picks a base repository from the clone's remotes and may choose upstream: the sync PR gets opened against qm, and gh pr edit 1 overwrites whatever PR is number 1 in the source repository. The same applies to gh pr view, gh pr list, and gh issue.

The description should state the upstream commit range merged, any file outside deploy/layers/ that conflicted and how it was resolved, and the results of the checks above.

When authorized to land a source-sync PR, preserve the upstream ancestry with a merge commit (gh pr merge --repo <source-fork> <pr> --merge) or an ancestry-preserving fast-forward. Never squash or rebase a source-sync PR, even if the repository's usual shipping workflow uses squash: that loses the upstream merge and causes later syncs to revisit already-integrated history. If repository settings prohibit merge commits, resolve that policy before landing; do not fall back to squash. Package dependency PRs can follow the deployment repository's ordinary merge policy.

If the private fork deploys from main, merging this PR ships upstream's changes to production, so merge when someone can watch it.

A source fork runs its enabled CI workflows in its own account. A sync that adds or changes CI changes what runs on the next PR, and workflows that need secrets the fork never received will fail until those are supplied.

Never do these

• git push --mirror to seed or update a source fork. It copies unrelated branches and tags, leaves initial default-branch selection implicit, and can delete destination-only refs. Seed only main and explicitly set the default branch as the README shows.
• Pushing a branch whose history contains organization commits to upstream. The upstream-pr skill pushes upstream only from branches cut fresh from upstream/main and scrubbed.
• Rebasing main onto upstream/main, or force-pushing a private fork's main.
• Resolving a conflict by deleting the upstream side wholesale to quiet the merge. That silently diverges core from upstream, and the divergence returns as a larger conflict in the next sync.