RUNBOOK — 🎖️ Solving α-AGI Governance 👁️✨

This runbook lets a non-technical owner execute the entire AGI Governance Demonstration from a laptop. Every action is copy‑pasteable; no bespoke coding is required. The workflow assumes access to an Ethereum mainnet RPC (or fork) and a hardware wallet, Safe, or custodial signer with owner privileges.

0. Prerequisites

1. Clone the AGI Jobs v0 (v2) repository and install dependencies:

   git clone https://github.com/MontrealAI/AGIJobsv0.git
   cd AGIJobsv0
   npm ci

2. Toolchain locks:

   npm run ci:verify-toolchain

   Confirms Node 22.23.3, Hardhat, Foundry, and auxiliary utilities match the pinned versions.
3. Owner signer ready: ensure you control the owner key or multisig referenced in config/mission@v1.json.

1. Generate the governance dossier

npm run demo:agi-governance

Outputs reports/governance-demo-report.md with:

• Thermodynamic energy margins (Gibbs free energy, Hamiltonian convergence envelope, Landauer limit calibration).
• Statistical-physics partition validation (partition function, scaled free energy, entropy, Gibbs delta tolerance, heat capacity).
• Jarzynski equality reconciliation (log ⟨e^−βW⟩ vs e^−βΔF confirming the Landauer-aligned free-energy gap).
• Incentive free-energy ledger (mint/burn/slash parity, treasury mirroring, owner-tunable slashing curves).
• Five-method diagnostics (discrete replicator, RK4 continuous flow, Perron eigenvector, closed-form, Monte-Carlo), including actual convergence flags, iteration counts, and the configured agreement threshold.
• Analytic vs numeric Jacobian matrices (Gershgorin, spectral radius, max delta) and antifragility curvature plus welfare growth curve for adversarial shocks.
• Alpha-field sovereign assurance scoreboard validating Stackelberg bounds, Gibbs tolerances, antifragility minimums, sigma welfare gains, owner coverage, owner supremacy index, thermo ↔ quantum alignment, quantum confidence, superintelligence index, and energy margin with assurance breakdowns.
• Quantum governance lattice (coherence confidence vs floor, quantum free-energy delta, Noether charge alignment, state entropy, superposition weights).
• Risk audit portfolio with weighted mitigation coverage, dual residual calculations, and board threshold comparison.
• Owner command surface (pause/unpause, parameter upgrades, treasury manoeuvres, sentinel verifications) plus capability coverage matrix and npm-script audit table.
• Blockchain deployment ledger (contracts, pausable selectors, Safe module stack).
• CI enforcement proof (required contexts, concurrency, access-control coverage).

Review the report. It references exact commands to execute each owner action on Ethereum or via AGI Jobs automation scripts.

Read equilibrium and conservation diagnostics correctly

The supplied mission@v1.json is a neutral cyclic game. Its exact interior equal-payoff equilibrium is (1/3, 1/3, 1/3), with payoff 1 for every strategy. That establishes equilibrium existence, not convergence from the configured initial state (0.42, 0.35, 0.23).

For its continuous replicator equations, the product x*y*z is conserved at 0.03381, below the value 1/27 at the uniform equilibrium. The trajectory therefore cannot converge to that interior point. An RK4 endpoint off equilibrium and a continuousConverged: false result are expected. Raising consistencyThreshold does not change the dynamics or establish convergence.

The report keeps the methods separate:

• closedForm solves the interior equal-payoff equations. Its payoff and simplex residuals are reported independently.
• replicator is the ensemble of discrete run estimates. replicatorEstimate identifies terminal estimates, tail-time averages after the iteration limit, or a mixture; replicatorIterations is the actual mean iteration count. A time average can be close to equilibrium while the trajectory continues moving.
• replicatorConverged requires all sampled discrete trajectories to meet numerical step and unilateral-payoff-gap tolerances. Tiny steps near an invadable boundary do not count as convergence.
• continuous is the actual RK4 endpoint. continuousConverged requires both the derivative norm and unilateral payoff gap to meet numerical tolerance. continuousDerivativeNorm remains visible even when the iteration limit is reached. These finite numerical criteria do not prove asymptotic stability or uniqueness.
• eigenvector is a Perron diagnostic, which need not equal the game's equilibrium for a general payoff matrix. monteCarlo is a random-start average; its RMS error describes individual final-state disagreement with the closed-form solution.
• methodConsistency only compares maximum pairwise vector distance with the explicitly reported consistencyThreshold. It does not assert that trajectories converged, that the equilibrium is unique, or that all five methods solve the same problem. The configured discount factor is not used to prove any such claim.

In particular, a coordination game can converge to boundary states different from the interior equilibrium. The Alpha-Meta mission reuses this engine and declares a wide agreement threshold; inspect the raw vectors, convergence flags, and errors even if that threshold passes. No solver output is replaced with the closed-form result to improve agreement.

Escrow conservation includes all four components: burned + treasury + employer + retained = jobEscrow. The supplied fixture allocates 3,000 + 1,000 + 1,000 + 45,000 = 50,000. The retained amount is the remaining worker-payout allocation, not missing funds. Configuration validation rejects negative basis points or allocation totals above 10,000 basis points.

Historical committed reports preserve the engine output from their original generation. Fresh reports add the diagnostics above and may differ from old summaries; generate a new dossier in a separate output directory before replaying it. Generation and same-engine replay demonstrate reproducibility, not independent mathematical certification or an on-chain execution. The focused governance tests include exact cyclic invariants and known stable/nonconvergent counterexamples as separate checks.

2. Recompute the dossier (independent verification)

npm run demo:agi-governance:validate

This command recomputes every analytic in the mission manifest—thermodynamics, statistical physics, replicator equilibria, antifragility curvature, risk aggregation, incentive ledgers, and owner control coverage—and compares them against the generated summary JSON. It emits reports/governance-demo-validation.json and .md, each listing the tolerance achieved per check plus confirmation that agent ↔ treasury parity, divergence tolerances, and Jacobian stability survived the replay.

Archive these files with the original dossier for an independently verified evidence chain.

3. Validate CI enforcement (green V2 shield)

npm run demo:agi-governance:ci

This audits .github/workflows/ci.yml to ensure:

• Jobs lint, tests, foundry, coverage, and summary exist with the expected display names.
• Push and pull request triggers are enabled for the workflow.
• Manual workflow_dispatch trigger is available for emergency reruns.
• Concurrency guards are active (ci-${workflow}-${ref}).
• cancel-in-progress is set to true so new pushes replace stale runs.
• Coverage thresholds are enforced (≥ 90%).
• COVERAGE_MIN environment variable is ≥ 90%.

Attach the generated reports/ci-verification.json to your governance logs.

4. Aggregate owner diagnostics (one-click audit pack)

npm run demo:agi-governance:owner-diagnostics

This orchestrates owner:audit-hamiltonian, reward-engine:report, owner:upgrade-status, and owner:compliance-report with --json, tolerating environments where Hardhat artifacts or on-chain addresses are absent. The resulting reports/owner-diagnostics.json and owner-diagnostics.md summarise success, warnings (e.g., skipped due to missing deployments), and actionable notes. Share the Markdown with executives and store the JSON for automated evidence pipelines.

5. Launch the grandiose governance console

open demo/agi-governance/reports/governance-demo-dashboard.html  # macOS
# or
xdg-open demo/agi-governance/reports/governance-demo-dashboard.html  # Linux

The dashboard renders the same mission data with:

• Flowing mermaid diagrams (energy → incentives → alpha field → owner loop, residual-risk pie, owner sequence, antifragility mindmap).
• Dedicated quantum lattice card with coherence confidence, Landauer delta, and Noether charge tolerance visualised alongside the superposition weight table.
• A live SVG antifragility curve driven by the recomputed welfare samples.
• Responsive tables for strategies, risk vectors, pausable selectors, and CI shields.

This gives non-technical owners a cinematic control room that mirrors the Markdown dossier without requiring terminal access.

Full automation run (optional)

To execute every governance drill—dossier generation, validation, CI verification, and owner diagnostics—in one command, run:

npm run demo:agi-governance:full

This produces reports/governance-demo-full-run.json and .md, capturing step durations, antifragility curvature, residual risk, CI shield verdicts, and owner readiness. Use the Markdown artifact when you need a single, board-ready proof that the entire α-AGI governance system executed without manual intervention.

6. Execute on-chain owner controls (optional live drill)

Each command below can be run via the CLI, Safe transaction builder, or Etherscan write interface. Replace placeholder addresses with your deployment addresses.

1. Pause the platform instantly (emergency brake):

   npm run owner:system-pause -- --network mainnet --pause true

   Validate pause state using npm run owner:verify-control.

2. Tune governance Hamiltonian parameters:

   npm run owner:command-center -- --network mainnet --target HamiltonianMonitor --set-lambda 0.94 --set-inertia 1.08

3. Adjust reward engine (Gibbs free energy alignment):

   npm run reward-engine:update -- --network mainnet --burn-bps 600 --treasury-bps 200

4. Update tax policy acknowledgement (public disclosure):

   npm run owner:update-all -- --network mainnet --module TaxPolicy --acknowledgement "Participants accept AGI Jobs v2 tax terms."

5. Queue an upgrade bundle for deterministic rollout:

   npm run owner:upgrade -- --network mainnet --proposal governance_bundle.json
   npm run owner:upgrade-status -- --network mainnet

6. Resume the platform:

   npm run owner:system-pause -- --network mainnet --pause false
   npm run owner:verify-control -- --network mainnet

Document transaction hashes in reports/governance-demo-report.md under the “Owner Execution Log” section.

Tip: Confirm the “Command Audit” table flips to all ✅ entries before executing upgrades. If a capability shows ⚠️, run npm run owner:surface to inspect available automation scripts or regenerate the AGI Jobs CLI package.

7. Formal verification hooks

1. Coverage remapping audit:

   npm run coverage
   node scripts/ci/remap-coverage-paths.js
   npm run check:access-control

2. Foundry stochastic fuzzing:

   forge test -vvvv --ffi --fuzz-runs 256

3. Red-team sentinel validation:

   npm run monitoring:sentinels
   npm run monitoring:validate

Archive the resulting artefacts inside reports/ alongside the governance dossier.

8. Evidence of execution

After each run:

1. Commit the generated artefacts to a dedicated evidence branch or upload them to immutable storage (e.g., IPFS, Arweave).
2. Cross-reference the timestamp with Safe/Etherscan transaction receipts.
3. Update the Owner Execution Log section in the dossier and tick the capability coverage table once each action has a confirmed transaction hash.
   • Transaction hash
   • Module touched
   • Parameter delta
   • Operator signature

The compiled dossier proves the owner maintains total control while the platform autonomously drives toward the thermodynamic and game-theoretic optimum.

Mission complete. AGI Jobs v0 (v2) now demonstrably empowers you—without bespoke engineering—to operate the civilisation-scale α-AGI governance engine.