Upgrade Guide

Last updated: 2026-05-23

When Protocol Changes

Protocol changes belong in agenc-protocol, which is private for now.

Sequence:

1. Update protocol source.
2. Confirm declare_id!, Anchor.toml, and branch policy match the target

deployment.

3. Run protocol validation.
4. Refresh committed artifacts when the IDL or target address changes.
5. Update @tetsuo-ai/protocol package artifacts.
6. Update SDK consumers.
7. Update Marketplace Agent Kit presets/policies if the mainnet target changed.
8. Update docs in the same release window.

Protocol gates:

npm ci
npm run artifacts:check
npm run build
npm run typecheck
npm run pack:smoke

Canary feature gates:

npm run canary:build
npm run canary:idl
npm run canary:check-idl
npm run canary:test

When SDK Changes

SDK changes belong in agenc-sdk.

Gates:

npm run build
npm run typecheck
npm run test
npm run api:baseline:check
npm run pack:smoke

Run focused devnet validators when task lifecycle, bids, disputes, governance, reputation, or skills change:

npm run test:devnet:deep:strict
npm run test:devnet:bid-marketplace
npm run test:devnet:disputes
npm run test:devnet:governance
npm run test:devnet:skills
npm run test:devnet:reputation

Do not rely on the SDK default PROGRAM_ID for mainnet canary. Pass the target program explicitly.

When Marketplace Kit Changes

Marketplace canary UX, signer policy, job-spec, artifact, wallet, Ledger, MCP, and agent rails belong in agenc-marketplace-agent-kit, which is private for now.

Update docs when changes affect:

The mainnet canary gate is:

agenc-marketplace --network mainnet --json canary check

It is not an agenc-core smoke script.

When Runtime Changes

Runtime, TUI, daemon, providers, MCP, skills, plugins, permissions, and coding tools belong in agenc-core.

Gates:

npm run typecheck
npm run build
npm run test
npm run validate:runtime

Update docs that describe:

Current Baseline

As of 2026-05-23:

HJsZ53Zb27b8QMRbQpuDngE44AdwCGxvEZr61Zmxw1xK

Do not reuse older docs that still reference:

Documentation Rule

Treat docs updates as release work.

At minimum, any upgrade that changes public behavior should update: