Upgrade Keel And Sync Upstream Instructions

Upgrading Keel in a downstream repository is a contract sync, not just a version bump. The binary can change command behavior, but the bigger risk is that the repo's copied instruction files stop matching the engine that humans and agents are actually running.

Explicit Work

Treat instruction sync as a real maintenance slice

Upgrading Keel is not just swapping a binary. It can change the operating contract that tells humans and agents how to use the board in your repo.

Narrow Diff

Start from upstream, preserve local seams

The safe move is to diff the upstream files, absorb new engine guidance, and then reapply the repo-specific wrappers and proof rules that your project actually needs.

Validation

Close the loop on the board

After syncing, rerun the health and board surfaces that prove the repository still behaves like a coherent Keel installation.

01

Snapshot

Read the current board before changing anything

keel doctor --status

Take a clean snapshot of the current operating state so you know whether the repo was healthy before the upgrade started.

02

Upgrade

Update the binary or dev-shell path

keel upgrade

Upgrade Keel through the same install path your repository actually uses: `keel upgrade` for release installs, `keel upgrade --ref <tag-or-sha>` for source snapshots, or a flake/dev-shell update for Nix-managed setups.

03

Diff

Compare upstream instruction files to your local copies

diff -u AGENTS.md /tmp/keel-upstream/AGENTS.md

Find the new engine guidance before you start editing. The goal is to merge upstream intent into your downstream contract, not to freestyle a replacement.

04

Reapply

Put the repo-specific seams back on top

keel hooks install

Restore local wrappers, proof contracts, and repo overview sections after the upstream sync so the repo remains usable in its actual environment.

05

Validate

Prove that the engine still fits the repository

keel flow --scene

Rerun the board surfaces that should still make sense after the change. If they drift, fix the contract now rather than leaving hidden ambiguity behind.

1. Snapshot current behavior

Before you touch the install path or the copied instruction files, read the board surfaces that matter now:

keel doctor --status
keel flow --scene
keel mission next --status

If those surfaces are already broken, fix that drift before the upgrade. Otherwise you will not know which problems came from the sync and which were already present.

2. Upgrade Keel through the path your repo actually uses

Use the same upgrade path that installed Keel in the first place:

• Nix-managed repo: update the flake input or dev-shell pin.
• Release-installer repo: run keel upgrade.
• Source-driven repo: run keel upgrade --ref <tag-or-sha> when you want Keel to fetch the cached source, build it with a supported local toolchain, and install it through the generated installer.

Do not change the instruction files first. Upgrade the engine, then sync the contract around the engine you are actually going to run.

Typical upgrade commands:

keel upgrade
keel upgrade --ref v0.2.1
keel upgrade --ref 533fa5b8

3. Diff upstream AGENTS.md and INSTRUCTIONS.md

Use a clean upstream checkout so you can compare the latest engine guidance against your repo-local copies:

git clone https://github.com/spoke-sh/keel.git /tmp/keel-upstream
diff -u /tmp/keel-upstream/AGENTS.md AGENTS.md
diff -u /tmp/keel-upstream/INSTRUCTIONS.md INSTRUCTIONS.md

While you review that diff, separate the changes into two piles:

• engine changes you should absorb
• repo-specific seams you must preserve

Engine changes usually include the tactical loop, new lifecycle guidance, new command expectations, or updated hygiene rules. Repo-specific seams usually include your wrappers, proof contract, project overview, and any local delegation guidance.

If the repo started from keel new, the generated AGENTS.md and INSTRUCTIONS.md already contain PROJECT-SPECIFIC blocks. Preserve those sections while absorbing upstream changes around them.

This is also where small-but-important behavioral changes show up. For example, upstream may tighten or relax heartbeat semantics, hook behavior, or commit-boundary hygiene. Those changes belong in your downstream copies of AGENTS.md and INSTRUCTIONS.md, not in tribal memory. The public reference point for that specific contract is now Heartbeat And Pacemaker.

4. Reapply the downstream seams deliberately

After the upstream sync, inspect each local surface that probably needs to stay different:

Surface	What to preserve downstream
Command wrappers	Repo-local helpers such as just mission, just screen, or direct keel ... usage instead of Keel-repo wrappers
Proof contract	The real product or runtime claim your repo must verify, not just generic board closure
Project overview	Repo description, directory map, important entrypoints, and local architecture notes
Delegation rules	Worker-context, steward, or harness-specific coordination rules that only matter in this repo
Adjacent harness docs	Extra files for specific harnesses that should continue to point back to the same board contract

The port repository shows this clearly: it keeps the upstream engine language around orientation, health, and lifecycle, but it swaps in direct keel ... commands, adds just mission and just screen, and carries a Mission Proof Contract that only Port can define.

5. Reinstall hooks and validate the engine

Once the files are synced, refresh the repo's automation and then re-read the board:

keel hooks install
keel heartbeat
keel doctor --status
keel flow --scene
keel mission next --status
keel pulse

Depending on the repo, you may also want to run local wrappers such as just check, just test, or project-specific smoke tests. The important part is that the board contract and the repo's actual command surface agree again.

If the scenes themselves changed upstream, also compare them against Scene Surfaces so your downstream docs keep describing the right visual logic.

note

Treat this as explicit board work when the repository is already under Keel. If the sync is material, open a story or maintenance voyage instead of silently editing the contract in a chat session.

What not to do

• Do not overwrite downstream files wholesale and assume you will remember the local seams later.
• Do not keep stale wrapper names when the repo has already moved to a different command surface.
• Do not leave hook installation or board validation for an undefined follow-up.
• Do not let harness-specific files drift away from AGENTS.md and INSTRUCTIONS.md.

The goal is not a perfect textual match with upstream. The goal is a downstream contract that still behaves like Keel while remaining truthful about the repository it governs.

Related reading

If you are setting up the downstream contract for the first time, start with Downstream Project Contracts.