Forge Card Migrate

forge_card_migrate — Federation Identity Plane Migration Skill

Single canonical path for migrating agent-cards. No other tool may write to agent-card.json files. Replaces ad-hoc schemaVersion bumps, scattered authority_ceiling additions, and orphaned registry_receipt_hash fixes. Forged 2026-09-08 from the federation identity plane audit. Backs the enforcement closure of schema v2.3.0 INV-005/INV-007 plus federation-invariants.md #11/#12/#13.

TRIGGER

THE CONTRACT (non-bypassable)

Every card mutation goes through forge_card_migrate. The skill enforces:

1. F1 AMANAH — every mutation writes a .bak-20260908-pre-migration companion first. Reversibility is a property of the file system, not a promise.
2. F2 TRUTH — registry_receipt_hash is computed from live SHA256 of the source file. The hash IS the truth; no metadata override.
3. F11 AUDITABILITY — every mutation emits a migrate_cards.py log line with path · mutations[] · sha256. No silent edits.
4. F13 SOVEREIGN — triple-identity collapse (Item 7 of the original action plan) is OUT OF SCOPE for this skill. That requires F13 sovereign go + 888_HOLD gate. This skill only handles additive migrations.

MIGRATION ACTIONS

Action 1: schemaVersion bump

# Before
{"schemaVersion": "2.2.0", ...}
# After (additive)
{"schemaVersion": "2.3.0", "$schema": "arifOS/agent-card/v2.3.0", ...}

Action 2: registry_receipt_hash populate

import hashlib
sha = hashlib.sha256(card_path.read_bytes()).hexdigest()
card["registry_receipt_hash"] = f"sha256:{sha}"
card["registry_snapshot_at"] = "2026-09-08T01:46:00Z"
card["registry_source"] = ["source_enumeration", "mcp_tools_list", "registry_api"]
card["registry_tool_count"] = {"source": 0, "registry": 0, "card": len(card.get("skills", []))}

Action 3: authority_ceiling populate (INV-13)

The AUTHORITY_CEILING_MAP in migrate_cards.py matches card path substring to canonical ceiling. Most-specific match wins. Defaults to OBSERVE_ONLY (safest).

Action 4: admissible gate (post-migration optimistic)

Sets card.admissible = true after migrations complete. The boot-parity verifier (separate skill: boot_parity_verifier) is the FINAL adjudication — it can demote cards that fail cross-tree uniqueness (INV-11) or other invariant checks.

INVARIANT BINDINGS

RUN MODES

# Default: discover + migrate all 48 cards (2 trees), print sample mutations
python3 /root/forge_work/2026-09-08-federation-identity-zen/migrate_cards.py

# Boot-parity verifier (paired skill — VALIDATES post-migration)
python3 /root/forge_work/2026-09-08-federation-identity-zen/boot_parity_verifier.py --report
python3 /root/forge_work/2026-09-08-federation-identity-zen/boot_parity_verifier.py --check  # CI gate, exit 1 on F4 violation

SCAR LEDGER

INVARIANT RECHECK

After every migration run, always re-run the verifier:

python3 boot_parity_verifier.py --report
# Expected output:
# ✓ Admissible: 38/38 (100%) after successful migration
# ✗ Inadmissible: 0

If inadmissible count > 0 → do NOT proceed to Item 7 (triple-identity collapse). The collapse becomes trust-not-sanitation.

DO NOT

• ❌ Edit agent-card.json files directly with edit / write_file — use this skill
• ❌ Run the migration without backing up (.bak-* is F1 AMANAH's contract)
• ❌ Skip the verifier step — "admissible=true on the card" ≠ "admissible in the registry"
• ❌ Add NEW schema versions — convergence to v2.3.0 is the goal, not new variants
• ❌ Touch triple-identity collapse (Item 7) — that's 888_HOLD territory

INTEGRATION

• Files: /root/forge_work/2026-09-08-federation-identity-zen/migrate_cards.py (script) + this SKILL.md
• Backed by: /root/AAA/instructions/federation-invariants.md (INV-11/12/13)
• Validated by: /root/forge_work/2026-09-08-federation-identity-zen/boot_parity_verifier.py
• Surface: GET /a2a/agents on AAA :3001 (wires the verifier into the gateway)

DITEMPA BUKAN DIBERI — Reversibility is the contract. Schema convergence is the goal. Identity entropy is the disease.