Update Qm

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.