@agent-teams/docs-protocol-agent-teams

Agent Teams managed integration for the portable @agent-teams/docs-protocol package.

This package exclusively owns Cohort authority, managed consumer state, transition projectors, managed workflows, managed qualification, and historical managed assets. It depends on the portable package through that package's public Node contracts; the portable package never discovers or imports this adapter.

The retained contract keeps profile 3 / Cohort 2 / state 2 / receipt 3 and the same public sync overload adds profile 4 / Cohort 3 / state 3 / docs-protocol-cohort-v3-qualification-receipt/v1 receipt 1 / packed policy 3. A Cohort binds exactly five npm

• @agent-teams/repository-mutation;
• @agent-teams/document-authoring;
• @agent-teams/docs-protocol;
• @agent-teams/docs-protocol-agent-teams; and
• @agent-teams/engineering-foundation.

A consumer declares only Docs Protocol, Docs Protocol Agent Teams, and Engineering Foundation as root development dependencies. Repository Mutation and Document Authoring remain exact transitive coordinates verified against the lockfile. Independent floating package updates are not Cohort authority.

The current runtime policy is policy 3.0.0 with an artifact-protected support claim. It records Node 26.11.1 as the production default and Node 24.21.0 as the compatibility lane. This nominal default and cutover metadata does not claim physical Node 26 qualification, and it does not make the managed candidate QUALIFIED or CANARY.

The managed runtime projection retains node-24-production-default and node-26-managed-qualified as nominal historical lane IDs. The retained Node 24 ID has default: false and does not claim that Node 24 is the current default. The Node 26 lane has default: true and records the actual 26.11.1 / pnpm 11.20.0 / Linux / x64 qualification runtime tuple, but the Cohort v3 candidate remains unselected with status candidate-unqualified until genuine registry qualification. The operational Profile 3 / Cohort 2 / receipt 3 contract remains explicitly Node 24 and unchanged.

Managed operations use the distinct executable:

agent-teams-docs-managed check --consumer .
agent-teams-docs-managed plan --consumer . --to COHORT
agent-teams-docs-managed apply --consumer . --expect sha256:DIGEST
agent-teams-docs-managed upgrade --consumer . --to COHORT --target-generation 2
agent-teams-docs-managed recover --consumer .
agent-teams-docs-managed qualify --consumer .

The portable agent-teams-docs and docs-protocol executables contain only generic documentation commands. There is no legacy agent-teams-docs consumer route, runtime compatibility bridge, optional adapter lookup, or dynamic version detection. V1 records are immutable historical migration and rollback evidence. Existing V1 consumers retain exact check, recovery, and same-generation upgrade commands, but those commands never infer or synthesize V2 and are not a cross-generation compatibility mode.

The explicit --target-generation 2 route performs the bounded, reversible, one-time Profile v1/Cohort v1 to Profile v3/Cohort v2 migration. It stages and proves the successor in a disposable copy, publishes once, and restores exact source evidence if activation fails. It is not a bridge, alias, dual writer, or permission to emit new v1 records.

Portable profile v4 is a separate, optional consumer change. The managed owner exports projectManagedPortableProfileV4(v3Bytes) to produce reviewable UTF-8 JSON (also valid YAML) from one strict portable profile v3. It preserves the consumer's authoring path, Skill route and semantic validator IDs, and explicitly sets blocker type open-decision, target statuses deferred / open, and incompatible subject statuses accepted / active. Unknown keys, duplicates, aliases, tags, mixed generations and paths incompatible with v4 are rejected. The projection only returns bytes; it does not read or write consumer files.

Qualify the successor Docs Protocol reader before selecting v4: v3-only readers reject it. Review the returned bytes and use the existing known-file transaction Plan/Apply workflow with the exact saved v3 preimage. Finish or preserve any pending transaction through its exact recorded recovery artifact first. Cohort upgrade commands do not automatically invoke this migration. Profile 4 / Cohort 3 / state 3 uses the sync overload, exact namespace and packed policy 3, and actual Node 26.11.1 / pnpm 11.20.0 / Linux / x64 observation; selected: false until genuine published QUALIFIED authority, and a supporting receipt is not CANARY.

The qualification fixture selects portable v4 explicitly and is tested against the reviewed portable producer candidate. Existing canonical asset generation and Cohort qualification mechanisms still compute their own digests. Restoring the saved v3 profile is an explicit rollback only while its paths and document vocabulary satisfy v3 and no incompatible transaction is pending; downgrading a package alone is not recovery. Published versions remain immutable.

For an explicit restorable 1-to-2 preparation, select an exact target lock with --target-lockfile /absolute/external/pnpm-lock.yaml --target-lockfile-sha256 sha256:HEX alongside upgrade --source-generation 1 --target-generation 2 --prepare --restoration-proof /absolute/external/proof.json --to COHORT. Both target-lock flags are required together. The digest uses 64 lowercase hexadecimal digits.

The input must be a nonempty regular file of at most 32 MiB, with canonical parents, no symlink or hardlink, outside the consumer, controller and kernel roots. Preparation retains the validated bytes, checks the selected cohort's strict runtime closure and preserves the original lock's comments, settings, importers and foreign graphs. Conflicts are rejected; no dependency merge occurs. Only the disposable staged lock is replaced, after normal managed projection. The selected mode installs with --prefer-offline --frozen-lockfile, retaining copy import, ignored scripts/pnpmfile and store-integrity checks. Preparation rejects any lock-byte or strict-closure change after installation and target apply.

Omitting these flags retains normal preparation behavior. Activation and restore remain offline and frozen. Existing preparation/proof schemas and deterministic controller build identity recording are unchanged. A new preparation must be reviewed with its own digest and retained controller; old proofs are not rewritten. Source tests do not establish public-package lifecycle qualification or release.

The transition catalog retains the exact qualified docs-2026-09-10-stable18, docs-2026-09-10-stable19, docs-2026-09-11-stable20 and docs-2026-09-12-stable21 projections and content-addressed Skill/caller bytes as successor upgrade origins and rollback evidence. A successor itself is qualified after publication, so it is never embedded into its own package. Historical generation2 bundles are strictly validated but excluded from the generation1 planner; their presence does not enable cross-generation execution or qualify a successor release.

Candidate generation3 execution

Unreleased source adds the explicit retained generation2-to3 transition and its selected original rollback. Published0.5.5 does not contain this path. It remains pending ADR-0070, reviewed API/decision promotion, published controller retention and physical consumer qualification. Source tests do not grant activation authority.

Retain a separately verified successor controller installation outside the consumer and keep its exact package/kernel builds available through restoration. Run it with actual Node24.21.0. Supply absolute AGENT_TEAMS_DOCS_UPGRADE_NODE24_EXECUTABLE, AGENT_TEAMS_DOCS_UPGRADE_NODE26_EXECUTABLE and AGENT_TEAMS_DOCS_UPGRADE_COREPACK_ENTRYPOINT paths. Source/target probes observe real Node24.21.0/26.11.1 on Linux/x64 and the exact root pnpm pin; target pnpm is11.20.0. Target activation and source restoration install frozen and offline. No runtime or engine fallback is provided.

The existing CLI route is explicit (variables below are operator-selected exact paths, Cohort IDs and the separately retained preparation digest):

"$NODE24" "$CONTROLLER/dist/cli.js" consumer upgrade --consumer "$CONSUMER" \
  --to "$TARGET_COHORT" --source-generation 2 --target-generation 3 \
  --prepare --restoration-proof "$PROOF" --json
"$NODE24" "$CONTROLLER/dist/cli.js" consumer finalize --consumer "$CONSUMER" \
  --from "$SOURCE_COHORT" --to "$TARGET_COHORT" \
  --source-generation 2 --target-generation 3 \
  --preparation "$PROOF.prepared" --expect "$PREPARATION_DIGEST" --proof "$PROOF" --json
"$NODE24" "$CONTROLLER/dist/cli.js" consumer restore --consumer "$CONSUMER" \
  --from "$TARGET_COHORT" --to "$SOURCE_COHORT" \
  --source-generation 3 --target-generation 2 \
  --preparation "$PROOF.prepared" --expect "$PREPARATION_DIGEST" --json

Preparation writes only the selected external intent. Finalize checks exact Git, consumer/controller/kernel identity, current complete images and fresh protected authority before RM publication. It re-observes the selected physical runtime and manager with network disabled before CAS; restore does the same for the origin. Reuse the same selected preparation after a crash; a fresh controller observes honest idempotent receipts, activates the target and records completion only after check. Automatic failure compensation requires this live attempt's all-replaced receipt. Otherwise use explicit restore; foreign or mixed images refuse overwrite. A completed selection cannot republish after its deliberate rollback. Recover an active file transaction through the existing exact-kernel consumer recover route before finalize/restore.

For a committed/merged consumer, reverse overlapping Host Stack/scripts/quality changes through their owner on the unmerged rollback PR branch first. Select its current clean HEAD/tree and use the separate committed-target route:

"$NODE24" "$CONTROLLER/dist/cli.js" consumer restore --consumer "$CONSUMER" \
  --from "$TARGET_COHORT" --to "$SOURCE_COHORT" \
  --source-generation 3 --target-generation 2 \
  --preparation "$PROOF.prepared" --expect "$PREPARATION_DIGEST" \
  --current-revision "$CURRENT_HEAD" --current-tree "$CURRENT_TREE" \
  --selection "$CURRENT_SELECTION" --json

This route proves source ancestry, the committed Cohort3 and exact managed images, then independently binds the current root and a fresh inverse plan. Unrelated Host files are preserved. Foreign whole-file package/lock/workspace or profile changes refuse; the managed owner does not patch Host fields. The public proofDigest now identifies this retained current selection. If that file already exists, select its digest separately with --selection-expect to resume; an uncertain write is never repeated automatically. Cold resume re-observes honest idempotent receipts and runs the old source installation/check under Node24. Moving HEAD, changing unrelated files or committing the rollback makes the old selection stale. Full consumer CI remains required after both owner reversals.

Ordinary profile4 check/plan/apply selects the Cohort3 planner directly. The public upgradeConsumerIntegration API requires targetGeneration: 1 | 2 | 3; retained preparation/finalize/restore are explicit CLI operations. The old1-to2 flags and proof family keep their contract. Portable profile4 migration remains separate. Real publication and qualification select the successor coordinates; no npm version is forecast here.