AgentKit Studio
Contributing

Patch governance

The full DSH host patch loop: import a maintenance branch, edit commits, export deterministic patches, and why hand-editing a .patch fails.

AgentKit Studio depends on a pinned DSH baseline and maintains a reviewed patch series on top of it. A patch is not an incidental diff; it is a build input with a digest, an ordering dependency, a verification matrix, and an exit condition. This page explains how to change one, and why bypassing the tooling and editing a .patch by hand always fails.

Why patches exist

DSH is the official host; we do not fork its source tree. Some product behavior (sidebar lifecycle, packaging identity, update feed, session events, native turn recovery) has to live in the host. The approach: keep changes on a maintenance branch and treat the patches as that branch's deterministic export.

FactValueSource
Pinned baseline version0.2.2-rc.1version in dsh-pin.json
Baseline commit66491b05… (full SHA)commit / baseCommit in dsh-pin.json
Upstream refdsh-v0.2.2-rc.1ref in dsh-pin.json
Current patch series53 patchespatches/dsh-v0.2.2-rc.1/manifest.json
Retired patches7retired in the same file
Patch directorypatches/dsh-v0.2.2-rc.1/patchDirectory in dsh-pin.json

Do not write version numbers from memory

The repository carries three historical directories — patches/dsh-v0.2.0-rc.2/, patches/dsh-v0.2.1-rc.2/, and patches/dsh-v0.2.2-rc.1/ — with 34, 64, and 53 patches respectively. Only the one dsh-pin.json points at is current; use it as the source of truth in docs.

Directory layout

dsh-pin.json                       Pinned baseline: version / commit / ref / patchDirectory / digests
patches/dsh-v0.2.2-rc.1/
├─ 004-sidebar-panel-lifecycle.patch   Sequence number + name + .patch
├─ 080-native-owned-turn-recovery-and-dispatch.patch
├─ …                                   53 files, applied in ascending order
├─ manifest.json                       Review metadata: category, risk, dependencies, verification, exit condition
└─ source.json                         Export descriptor: commit sequence, tree, bundle digest
host-source/dsh-v0.2.2-rc.1/
└─ maintenance.bundle                  Git bundle with the baseline prerequisite and the maintenance branch

PATCH_ROOT is derived by the Makefile from patchDirectory in dsh-pin.json, defaulting to patches/dsh-v0.2.2-rc.1. DSH_MAINTENANCE_ROOT is your own maintenance checkout and must be set explicitly.

The four-step workflow

1. Import the maintenance source

make patch-source-import DSH_MAINTENANCE_ROOT=../dsh-maintenance

It first runs a read-only check of the current series (descriptor, bundle digest, commit inventory), then checks out the maintenance branch from maintenance.bundle into a brand-new directory. An existing target directory is rejected outright — this command never overwrites and never resets, it only creates.

2. Edit maintenance commits

Make your change in the maintenance checkout, then one patch per commit:

cd ../dsh-maintenance
git commit -m "004: fix sidebar panel lifecycle

Studio-Patch: 004"

Two hard rules:

  • Linear history only. The commit graph is a straight line from baseCommit; no merges.
  • A Studio-Patch: <id> trailer is mandatory. Export aligns commits with manifest entries by it.

3. Export the patches

make patch-source-export DSH_MAINTENANCE_ROOT=../dsh-maintenance

Export refuses a dirty working tree. It walks baseCommit..HEAD commit by commit to produce unified diffs, recomputes each patch's sha256, the tree patchedTree, and patchedSourceSha256, rebuilds maintenance.bundle, and writes source.json and manifest.json back. Repeated exports are byte-identical — as long as the commit and branch are unchanged, the export is deterministic.

4. Verify the patches

# Read-only: descriptor and export digests
make patch-source-check

# Full: regenerate patches from the bundle, compare byte by byte, verify Git ancestry
make patch-source-verify DSH_ROOT=../deepseek-harness

patch-source-check needs no DSH checkout and fits a fast loop; patch-source-verify needs a real checkout and is the last gate before you commit.

Why you cannot edit a .patch directly

Because a patch is bound in five places, and every one of them fails on a hand edit:

BindingEnforced byWhat a direct edit produces
Per-patch sha256 versus file contentcheck-patch-manifest.mjscontent digest mismatch
affectedFiles versus the --- a/ +++ b/ path setSameunregistered modified files
Manifest order and dependency orderSamemanifest order differs from application order
source.json commit sequence, tree, bundle digestdsh-maintenance-source.mjsgenerated patch differs or bundle digest mismatch
Whether the file is a legal unified diffcheck-patch-format.mjsGit rejected the unified diff syntax

In other words: a patch is an export, not a source file. The source is the maintenance commit. Editing the export is editing a build artifact.

Patch metadata

Every entry in manifest.json requires these fields; omitting one fails the gate:

FieldAllowed valuesPurpose
idThree digits, e.g. 004Stable identifier matching the filename prefix
categoryproduct / packaging / lifecycle / session-contract / general-fix / generated-docs / updater / signingClassifies the blast radius
risklow / medium / highSets the review bar
dependsOnArray of other idsMust point at earlier patches in the series
affectedFilesThe paths the patch actually changesCompared item by item with the diff
affectedPackagesAffected npm package namesDeclares the surface
contractsHuman-readable guaranteeWhat this patch promises
maintainerRoleMaintainer roleWho owns it
upstreamStatus.stateunverified / not-submitted / pending / merged-unreleased / in-baselineUpstream progress
upstreamStatus.evidenceTextWhy that state holds
removeWhenTextExit condition: when this patch can be deleted
verification.hostTests*.spec.* pathsHost-side regressions
verification.integrationsNames declared in verificationProfilesIntegration tiers
verification.nativeTestsnative/system/test/*.test.jsNative-side regressions

verificationProfiles currently declares 13 tiers: source, web, electron, lifecycle, frozen, persistence, macos, windows, installed-update, dsh-web, product-profiles, node-projection, and native.

Retiring a patch

Once upstream ships the fix, retire the patch instead of deleting it:

  1. Remove the entry from the patches array.
  2. Add a record to retired, for example { "id": "004", "reason": "…" }.
  3. Re-export and verify.

A retired id may not collide with an active id, and reason must be non-empty — so "why did this patch disappear" always has an answer.

Common failures

ErrorCauseFix
import output already existsTarget directory already existsChoose a new directory; never reuse
export requires the declared maintenance branchThe checkout is not on refs/heads/codex/*Switch back to the declared branch
commit maintenance edits before exportingDirty working treeCommit first
maintenance history must be a linear chainA merge commit is presentRebase into a straight line
commit order or Studio-Patch trailer differsMissing or misordered trailerAdd Studio-Patch: <id>
empty maintenance commitA commit has no real changeSquash or drop it
commit count differs from patch inventoryCommit count differs from manifest entriesOne patch per commit
cyclic dependenciesdependsOn forms a cycleSplit or reorder
DSH checkout 有未提交改动Checkout is dirty before make patch-checkUse an isolated checkout

Next: confirm your change passes make release-check in Gates and verification.

On this page