AGI Jobs v0 (v2)

CI (v2) CI (v2) job wall Static Analysis Fuzz Webapp Containers Orchestrator E2E Security Scorecard

AGI Jobs v0 (v2) brings together job contracts, agent gateways, validators, operator consoles, orchestration, simulations, and demos. The architecture aims to support verifiable agent work with owner-controlled governance and observable execution.

Start here: Local setup and role guide · Production readiness and remaining blockers · Demo guide and complete catalog · Documentation catalog.

Design useful work: Job planner · Machine labor delivery workflow. Ten concrete work categories, exact proposal amounts, source boundaries and downloadable tasks compatible with the existing admitted computer-work adapter.

Review delivered work: Evidence reviewer · Review guide. Compare the admitted task with a worker receipt, verify exact artifact bytes and record acceptance findings locally. Hash consistency does not establish provider provenance or authorize settlement.

Explore the demos visually: AGI Jobs Demo Observatory — searchable collection, individual demo pages, original guides and flowcharts, and a browser-only job walkthrough. Website source and publishing instructions.

Coordinate computer-based work: the computer-work integration connects admitted jobs to isolated OpenClaw workers, including their configured native Codex Computer Use capabilities. Start with the supplier-desk browser lab: it produces real browser evidence and separately checks both a correct and an incorrect recommendation. Live workers require explicit task admission, protected credentials and independent acceptance review. The vision's $40T/year opportunity is a planning assumption, not a verified market-size or revenue claim.

Exercise the production gates locally: run npm run production:rehearse after dependency setup in a clean committed checkout. The production rehearsal combines real cryptographic checks, HTTP fault injection, adversarial contract tests, and three settled local jobs into an inspectable, signed simulation report.

Deployment status: local tests are not a mainnet certification. The four previously oversized contracts now use fixed implementations and staged deployment, and the size gate passes with normal Ethereum limits enforced. Release still requires authorized signing keys, completed deployment configuration, and passing CI. All existing architectural diagrams and demonstration surfaces are retained.

flowchart LR
    classDef core fill:#f3e8ff,stroke:#7c3aed,color:#2e1065,stroke-width:1px;
    classDef guard fill:#dcfce7,stroke:#16a34a,color:#14532d,stroke-width:1px;
    classDef ops fill:#e0f2fe,stroke:#0284c7,color:#0c4a6e,stroke-width:1px;
    classDef owner fill:#fef3c7,stroke:#d97706,color:#7c2d12,stroke-width:1px;

    OwnerConsole[[Owner command center CLI]]:::owner --> AuthorityMatrix[Owner authority matrix<br/>`npm run owner:verify-control`]:::guard
    AuthorityMatrix --> Contracts{{Contracts + Paymasters}}:::core
    Contracts --> Agents{{Agent gateway & orchestrators}}:::core
    Agents --> Demos{{Demonstration suites + simulations}}:::core
    Demos --> Observability[[Observability fabric<br/>`reports/**`]]:::ops
    Observability --> CIStatus[[CI v2 status wall]]:::guard
    CIStatus --> BranchProtection[[Branch protection guard]]:::guard
    BranchProtection --> OwnerConsole

The loop above describes the intended verification path. CI checks owner authority manifests and generates telemetry artifacts; effective merge protection also depends on the repository rules. A passing test run does not replace contract deployability checks, deployment verification, or operational commissioning.

Documentation lattice

The repository’s manuals, runbooks, and subsystem READMEs are catalogued in docs/readme-catalog.md. Use it to locate operator instructions and subsystem diagrams. The demo guide adds a generated inventory of every tracked demo directory and its nested guides; the Demo gallery workflow rejects a stale demo inventory. Document indexing and test results establish their stated coverage, not automatic verification of every narrative claim.

mindmap
  root((Knowledge lattice))
    Operator runbooks
      OperatorRunbook.md
      RUNBOOK.md
      Operator console quickstarts
    Intelligence dossiers
      docs/AUDIT_DOSSIER.md
      docs/AGI_Jobs_v0_Whitepaper_v2.md
      docs/legal-regulatory.md
    CI manifest
      ci/README.md
      docs/status-wall.md
      reports/ci/status.md
    Owner authority
      scripts/v2/ownerControl*.ts
      reports/owner-control/**

Use the catalogue to jump directly into any subsystem; the documents are regenerated whenever directories shift so the map never falls out of sync with the codebase.

Owner command authority

The contract owner controls the documented governance entry points. Owner-control commands produce reviewable artefacts (reports/owner-control/**), and CI checks the configured authority manifests. Effective merge enforcement additionally requires active repository branch rules; a workflow alone does not prevent an unchecked merge.

Owner commands have different side effects and prerequisites. Read the command-specific runbook before execution: live checks require RPC access, and transaction commands may write on-chain. Use only the preview and output flags supported by that command. Combine them with npm run owner:plan:safe to produce multisig-ready transaction bundles when deploying from custodial safes. (package.json) (run-owner-plan.js)

sequenceDiagram
    participant Owner
    participant CommandCenter as Owner command center
    participant Ledger as Contracts & paymasters
    participant Guardians as Multisig / guardian set
    participant CI as CI v2 guard

    Owner->>CommandCenter: Trigger owner:* command
    CommandCenter->>Ledger: Prepare signed transaction set
    Ledger-->>CommandCenter: Emit state proofs + receipts
    CommandCenter->>Guardians: Publish approval packets / safe bundle
    CommandCenter->>CI: Upload authority artefacts
    CI-->>Owner: Gate merge until verification passes

The resulting artefacts feed the Owner control assurance CI job and the branch protection guard so every production deployment is traceable back to an approved owner command path. (ci.yml)

Release provenance lattice

Every release tag must be cryptographically attributable to the guardians who shepherd AGI Jobs v0 (v2). The .github/signers/allowed_signers register contains illustrative placeholders, not usable maintainer keys. Preserve the examples for reference and replace them with authorized SSH public keys before a production release. (allowed_signers) Execute npm run ci:verify-signers to enforce actual OpenSSH key parsing, namespace scoping, and duplicate detection. This check intentionally fails on the shipped placeholders. (package.json) (check-signers.js)

flowchart LR
    classDef register fill:#fef3c7,stroke:#d97706,color:#7c2d12,stroke-width:1px;
    classDef guardian fill:#dcfce7,stroke:#16a34a,color:#14532d,stroke-width:1px;
    classDef ci fill:#0ea5e9,stroke:#0284c7,color:#0f172a,stroke-width:1px;
    classDef release fill:#ede9fe,stroke:#7c3aed,color:#312e81,stroke-width:1px;

    Guardians((Guardian hardware keys)):::guardian --> SignerRegistry[[`.github/signers/allowed_signers`]]:::register
    SignerRegistry --> ProvenanceCheck[[`npm run ci:verify-signers`]]:::ci
    ProvenanceCheck --> BranchGuard[[Branch protection guard]]:::ci
    BranchGuard --> ReleaseTag[[`git tag -v` release verification]]:::release
    ReleaseTag --> Guardians

The release workflow fails closed if a maintainer attempts to publish a tag without a registered key, preserving the intelligence engine’s audit trail while giving the owner full power to rotate, pause, or expand the guardian set at will. (check-signers.js)

CI v2 status wall (live)

The full mapping between wall entries, workflow job identifiers, and maintenance steps lives in docs/status-wall.md. ci/required-contexts.json defines the intended required checks, and CI summary aggregates its upstream signals. Repository branch rules must be configured separately to make these checks mandatory for merging. Release captains can inspect current results with npm run ci:status-wall -- --require-success --include-companion --format markdown. Badges below use GitHub's workflow-status endpoint; the job query parameter does not establish an individual job's result. Inspect the linked run and its job list for exact evidence. (README.md) (check-ci-status-wall.ts)

Companion workflows complete the assurance wall: static analysis, fuzz, webapp, containers, and e2e. Required contexts for those workflows are defined in ci/required-companion-contexts.json and enforced by npm run ci:verify-companion-contexts.

Live verification CLI

• Run npm run ci:status-wall -- --token <github_token> to confirm the latest ci (v2) run on main succeeded across every required job. The command inspects the GitHub Actions API, flags missing or red jobs, and prints a breakdown with direct links to each job log. Add --format markdown to render a README-ready table or --format json when you need structured output for dashboards or automated release gates. (check-ci-status-wall.ts)
• Pass --include-companion to extend the check across the companion workflows (static-analysis, fuzz, webapp, containers, e2e) so the full assurance wall is verified in one sweep. (check-ci-status-wall.ts) (required-companion-contexts.json)
• Use --branch <name> or --workflow <file> when validating release branches or pre-flight changes in forks. All options mirror the automation that the branch-protection guard enforces on protected branches. (check-ci-status-wall.ts)

flowchart TD
    classDef entry fill:#0ea5e9,stroke:#0284c7,color:#f8fafc,stroke-width:1px;
    classDef api fill:#6366f1,stroke:#312e81,color:#e0e7ff,stroke-width:1px;
    classDef guard fill:#facc15,stroke:#ca8a04,color:#1e1b4b,stroke-width:1px;
    classDef artefact fill:#10b981,stroke:#064e3b,color:#f0fdf4,stroke-width:1px;

    statusWall["ci:status-wall CLI\n(Operator command)"]:::entry --> ghRuns["GitHub Actions\nruns API"]:::api
    statusWall --> ghJobs["GitHub Actions\njobs API"]:::api
    ghRuns --> manifest["ci/required-contexts.json\n(required wall)"]:::guard
    ghJobs --> companion["ci/required-companion-contexts.json\n(companion wall)"]:::guard
    manifest --> verdict["Branch protection guard\nparity check"]:::guard
    companion --> verdict
    verdict --> artefacts["reports/ci/status.{md,json}\nmission artefacts"]:::artefact

The same manifest powers the branch-protection guard inside CI v2 and the local verification CLI, so green walls locally guarantee green walls on GitHub before merge. (ci.yml) (required-contexts.json)

API-level verification

Executive operators can independently corroborate the wall without local tooling by interrogating the GitHub REST API. With curl and jq installed:

# 1. Inspect the most recent workflow result on main
curl -s 'https://api.github.com/repos/MontrealAI/AGIJobsv0/actions/workflows/ci.yml/runs?branch=main&per_page=1' \
  | jq -r '.workflow_runs[0].status, .workflow_runs[0].conclusion'

# 2. Capture the run identifier for downstream job queries
RUN_ID=$(curl -s 'https://api.github.com/repos/MontrealAI/AGIJobsv0/actions/workflows/ci.yml/runs?branch=main&per_page=1' \
  | jq -r '.workflow_runs[0].id')

# 3. Enumerate job conclusions for that run
curl -s "https://api.github.com/repos/MontrealAI/AGIJobsv0/actions/runs/${RUN_ID}/jobs?per_page=100" \
  | jq -r '.jobs[] | "\(.name): \(.conclusion)"'

# 4. Assert every job concluded successfully (exit code 0 means green wall)
curl -s "https://api.github.com/repos/MontrealAI/AGIJobsv0/actions/runs/${RUN_ID}/jobs?per_page=100" \
  | jq -e 'all(.jobs[].conclusion == "success")'

The final check returns true and a zero exit status only when each required context is green, enabling air-gapped compliance suites or third-party dashboards to verify the wall without invoking repository scripts. Combine the API snapshot with npm run ci:status-wall -- --require-success --include-companion to cross-check manifest-driven expectations against the live Actions event stream. (check-ci-status-wall.ts)

Double-green enforcement drill

1. Interrogate the wall: npm run ci:status-wall -- --token <github_token> --require-success --include-companion must return all ✅ lines and regenerate both Markdown and JSON artefacts in reports/ci/. Cross-check the printed run ID with the Actions UI so the command and GitHub agree on the latest passing workflow. (check-ci-status-wall.ts)
2. Lock the manifest: Immediately execute npm run ci:sync-contexts -- --check to prove that the required context manifest still mirrors .github/workflows/ci.yml. The command fails fast on any drift so branch protection cannot silently fall behind. (update-ci-required-contexts.ts) (required-contexts.json)
3. Audit the rule: Finish with npm run ci:verify-branch-protection -- --owner MontrealAI --repo AGIJobsv0 --branch main --require and archive the console output. The script queries the GitHub REST API and enforces parity with the manifest, so a single invocation validates CI status, manifests, and the live protection rule in one sweep. (verify-branch-protection.ts)

flowchart TD
    classDef cli fill:#ecfeff,stroke:#0369a1,color:#0f172a,stroke-width:1px;
    classDef api fill:#f1f5f9,stroke:#1e293b,color:#0f172a,stroke-width:1px;
    classDef guard fill:#fefce8,stroke:#ca8a04,color:#713f12,stroke-width:1px;
    classDef artefact fill:#f5f3ff,stroke:#7c3aed,color:#4c1d95,stroke-width:1px;

    statusCLI[ci:status-wall]:::cli --> ghRunsAPI[GitHub Actions runs API]:::api
    statusCLI --> statusArtefacts[reports/ci/status.{md,json}]:::artefact
    manifestCheck[ci:sync-contexts --check]:::cli --> workflowFile[.github/workflows/ci.yml]:::guard
    manifestCheck --> manifestJSON[ci/required-contexts.json]:::guard
    branchAudit[ci:verify-branch-protection]:::cli --> githubBranchAPI[GitHub branch protection API]:::api
    manifestJSON --> branchAudit
    workflowFile --> branchAudit
    branchAudit --> enforcementReceipt[Archived enforcement log]:::artefact

Running the drill before every release forces status verification, manifest locking, and branch protection auditing to agree, creating a triple-check loop that mirrors CI v2’s internal guard rails. (ci.yml) (required-contexts.json)

Executive signal

• Unification: Smart contracts, agent gateways, demos, and analytics are orchestrated as one lattice, keeping governance, telemetry, and delivery in lockstep for non-technical operators. (README.md) (README.md) (README.md)
• Owner supremacy: Every critical lever is surfaced through deterministic owner tooling so the contract owner can pause, upgrade, and retune parameters on demand, without redeploying or editing code. (OwnerConfigurator.sol) (package.json)
• Evergreen assurance: CI v2 enforces a wall of 23 required contexts plus companion workflows, uploads audit artefacts, and verifies branch protection so operators can inspect the required evidence before approving a release. Check the current run and repository rules rather than assuming all checks are green. (ci.yml) (required-contexts.json) (required-companion-contexts.json)

Owner dominion console

The platform’s operator CLI renders full-spectrum control to the contract owner without touching Solidity or TypeScript. Each command combines deterministic manifests from config/ with the governance façades inside contracts/v2/admin so pauses, treasury updates, and validator quotas can be reconfigured in minutes while CI records immutable artefacts. (README.md) (README.md) (ci.yml)

flowchart LR
    classDef deck fill:#f0f9ff,stroke:#0ea5e9,color:#0c4a6e,stroke-width:1px;
    classDef manifest fill:#ecfdf5,stroke:#10b981,color:#064e3b,stroke-width:1px;
    classDef contract fill:#ede9fe,stroke:#7c3aed,color:#4c1d95,stroke-width:1px;
    classDef ci fill:#fef3c7,stroke:#d97706,color:#7c2d12,stroke-width:1px;

    manifests[config manifests]:::manifest --> ownerCli[owner:* CLI deck]:::deck
    ownerCli --> configurator[OwnerConfigurator<br/>+ owner-control scripts]:::contract
    ownerCli --> pauseSwitch[SystemPause<br/>+ thermostat orchestration]:::contract
    configurator --> ciArtefacts[CI owner assurance<br/>artefacts]:::ci
    pauseSwitch --> ciArtefacts

The same commands run automatically in the Owner control assurance job, so the checks wall refuses a merge unless the owner retains total dominion over pause switches, treasury routing, and upgrade paths. (ci.yml)

Quickstart for operators

1. Use Node.js 22.23.3 (.nvmrc/.node-version) and Python 3.12 to match the automated toolchain. (.nvmrc) (ci.yml) If your base image is missing node/npm, install the pinned version explicitly so tests don’t fall back to distro defaults, then validate the toolchain with npm run doctor:node so Hardhat builds don’t silently run under the wrong runtime. (check-node.js) (package.json)

   # With nvm installed, use the repository's exact Node pin.
   nvm install
   nvm use
   npm install --global npm@10.8.2
   npm run doctor:node

2. Hydrate dependencies (do not omit optional packages—the Hardhat toolbox requires the platform-specific @nomicfoundation/solidity-analyzer-* binary and will fail exactly like CI if you pass --omit=optional):

   CYPRESS_INSTALL_BINARY=0 npm ci
   python3.12 -m venv .venv
   source .venv/bin/activate
   python -m pip install --upgrade pip
   python -m pip install -r requirements-python.txt
   python -m pip check

3. Confirm the deterministic toolchain locks before coding:

   npm run ci:preflight
   npm run ci:verify-toolchain
   npm run ci:sync-contexts -- --check
   npm run ci:verify-contexts
   npm run ci:verify-companion-contexts
   npm run ci:verify-summary-needs

   The sync command confirms ci/required-contexts.json matches the workflow before the verification scripts enforce ordering, and the summary check proves the wall coverage is intact—keeping this quintet green locally mirrors branch protection expectations. (package.json) (update-ci-required-contexts.ts) (check-summary-needs.js) (ci.yml)
4. Validate the critical suites (prime the Hardhat cache once so local runs mirror CI performance):

   npm run compile           # generates artifacts exactly like the tests job
   npm test                  # reuses the compiled artefacts, matching ci (v2) / Tests
   npm run lint:ci
   npm run coverage
   forge test -vvvv --ffi --fuzz-runs 256

   Compiling first avoids the local fallback where hardhat test --no-compile triggers a fresh Solidity build, bringing the experience in line with the workflow’s dedicated compile step before npm test. These commands reproduce the Hardhat, linting, coverage, and Foundry stages the pipeline requires. (package.json) (ci.yml) The Python coverage harness additionally exercises the HGM worker dispatcher and sharded simulation CLI so CI’s 85% gate reflects the orchestrator workloads developers rehearse locally. (test_worker.py) (test_harness.py) (test_sharded_simulation.py)
5. When the signal is green, push signed commits and open a pull request—CI v2 enforces the exact same contexts on main and PRs.

Repository atlas

flowchart LR
    classDef core fill:#0ea5e9,stroke:#0369a1,color:#f8fafc,stroke-width:1px;
    classDef ops fill:#6366f1,stroke:#312e81,color:#eef2ff,stroke-width:1px;
    classDef demos fill:#f97316,stroke:#9a3412,color:#fff7ed,stroke-width:1px;
    classDef svc fill:#22c55e,stroke:#166534,color:#ecfdf5,stroke-width:1px;

    contracts[contracts/]:::core --> ci[ci/]:::ops
    contracts --> contractsOwner[contracts/v2/admin/]:::core
    agentGateway[agent-gateway/]:::svc --> services[services/]:::svc
    apps[apps/]:::svc --> demos[demo/]:::demos
    backend[backend/]:::svc --> deploy[deploy/]:::ops
    docs[docs/]:::ops --> reports[reports/]:::ops
    ci --> workflows[.github/workflows/]:::ops
    demos --> orchestrator[orchestrator/]:::svc
    ownerScripts[scripts/v2/]:::ops --> contractsOwner
    ownerScripts --> workflows

Control-plane architecture

flowchart TD
    classDef entry fill:#0ea5e9,stroke:#0284c7,color:#f8fafc,stroke-width:1px;
    classDef contract fill:#6366f1,stroke:#312e81,color:#eef2ff,stroke-width:1px;
    classDef service fill:#f97316,stroke:#9a3412,color:#fff7ed,stroke-width:1px;
    classDef ci fill:#22c55e,stroke:#166534,color:#ecfdf5,stroke-width:1px;

    subgraph Operator Surface
        gateway[Agent gateway APIs]:::service
        consoles[Operator consoles (`apps/`)]:::service
        ownerDeck[Owner CLI + control scripts]:::entry
    end

    subgraph Intelligence Core
        contractsStack[Contracts kernel + modules]:::contract
        orchestratorSvc[Orchestrator services]:::service
        sentinels[Sentinel & thermostat services]:::service
    end

    subgraph Assurance Lattice
        ciMain[CI v2 pipelines]:::ci
        companion[Companion workflows]:::ci
        reports[Audit & CI reports]:::ci
        branchGuard[Branch protection guard]:::ci
    end

    ownerDeck --> gateway
    ownerDeck --> orchestratorSvc
    consoles --> gateway
    gateway --> contractsStack
    orchestratorSvc --> contractsStack
    sentinels --> orchestratorSvc
    sentinels --> reports
    ciMain --> reports
    companion --> reports
    branchGuard --> reports
    reports --> ownerDeck
    reports --> consoles

The control plane ties owners, operators, and automation into one verifiable surface: owners drive changes through deterministic CLI entry points, agent services marshal those commands into contract-safe transactions, and sentinel services plus CI pipelines export signed artefacts for audits. (package.json) (README.md) (README.md) (README.md)

Owner command authority

flowchart TD
    classDef owner fill:#fefce8,stroke:#ca8a04,color:#713f12,stroke-width:1px;
    classDef script fill:#ecfdf5,stroke:#10b981,color:#064e3b,stroke-width:1px;
    classDef contract fill:#eff6ff,stroke:#2563eb,color:#1e3a8a,stroke-width:1px;

    Owner((Contract Owner)):::owner --> CommandCenter[owner:command-center]:::script
    CommandCenter --> OwnerConfigurator[[OwnerConfigurator]]:::contract
    Owner --> OwnerUpdate[owner:update-all]:::script --> Registry[[JobRegistry]]:::contract
    Owner --> OwnerPause[owner:system-pause]:::script --> SystemPause[[SystemPause]]:::contract
    Owner --> Authority[ci:owner-authority]:::script --> Matrix[(Owner authority matrix)]:::contract

Preview and export support varies by command; confirm the documented flags before supplying RPC credentials or signing transactions. (ownerControlDoctor.ts) (ownerControlQuickstart.ts)

Attestation registry safety lever

• AttestationRegistry.pause() / unpause() — owner-only circuit breaker that halts ENS-backed delegation while responding to compromised subdomains. Use the OwnerConfigurator (owner:update-all) or Hardhat console to invoke the pause, then resume once the attestor set is remediated. The mutation path is guarded by OpenZeppelin Ownable + Pausable, and attestation calls revert with Pausable: paused until unpaused. (AttestationRegistry.sol)

Governance oversight loop

flowchart LR
    classDef actor fill:#fefce8,stroke:#ca8a04,color:#713f12,stroke-width:1px;
    classDef auto fill:#ecfdf5,stroke:#10b981,color:#064e3b,stroke-width:1px;
    classDef guard fill:#eff6ff,stroke:#2563eb,color:#1e3a8a,stroke-width:1px;
    classDef repo fill:#f1f5f9,stroke:#1e293b,color:#0f172a,stroke-width:1px;

    OwnerCouncil((Owner council)):::actor --> ControlDoctor[Owner control doctor]:::auto
    ControlDoctor --> AuthorityMatrix[(Owner authority matrix)]:::guard
    AuthorityMatrix --> BranchGuard[Branch protection guard]:::guard
    BranchGuard --> GitHub[GitHub branch protection]:::repo
    GitHub --> CIWall[ci (v2) / CI summary]:::guard
    CIWall --> Reports[reports/ci/status.{md,json}]:::repo
    Reports --> OwnerCouncil
    Reports --> Operators[Operator consoles]:::auto

The governance loop keeps owner supremacy verifiable: owner council scripts regenerate the authority matrix, CI v2 enforces branch protection parity, and the resulting artefacts cycle back into operator consoles and decision briefings. (ci.yml) (README.md) (ownerControlDoctor.ts)

Parameter recalibration pipeline

flowchart LR
    classDef inputs fill:#ecfeff,stroke:#0369a1,color:#0f172a,stroke-width:1px;
    classDef analysis fill:#f5f3ff,stroke:#7c3aed,color:#4c1d95,stroke-width:1px;
    classDef command fill:#fef3c7,stroke:#d97706,color:#7c2d12,stroke-width:1px;
    classDef execution fill:#eff6ff,stroke:#2563eb,color:#1e3a8a,stroke-width:1px;

    configs[Config manifests\n(config/, storage/)]:::inputs --> surface[owner:surface]:::analysis
    surface --> matrix[owner:parameters]:::analysis
    matrix --> doctor[owner:doctor]:::analysis
    doctor --> mission[owner:mission-control]:::command
    mission --> updateAll[owner:update-all]:::execution
    updateAll --> contractsCore[contracts/v2 core modules]:::execution

• Surface scan: npm run owner:surface fingerprints every config file, normalises addresses, and highlights drift against the deployed control plane so owners see exactly which modules need attention before touching the chain. (ownerControlSurface.ts)
• Matrix export: npm run owner:parameters renders markdown, JSON, and mermaid matrices that map every subsystem to its calibration commands and verification steps, ready to drop into compliance reports or mission reviews. (ownerParameterMatrix.ts)
• Doctor triage: npm run owner:doctor scores each subsystem with pass/warn/fail, escalates on missing keys, and recommends remediation commands, enforcing deterministic ownership of the entire lattice. (ownerControlDoctor.ts)
• Mission orchestration: npm run owner:mission-control condenses the owner dossier, parameter diffs, and pause levers into a single decision brief for final sign-off. (ownerMissionControl.ts)
• Deterministic execution: npm run owner:update-all streams the plan into Hardhat transactions or Safe bundles so parameter updates and address rotations land atomically, with artifacts saved alongside the CI owner-control reports. (updateAllModules.ts)

Each stage emits markdown and JSON artefacts beneath reports/owner-control/, the same directory uploaded by CI v2 to prove the owner still wields ultimate authority while the automation remains fully transparent. (ci.yml)

CI v2 orchestration

flowchart LR
    classDef base fill:#ecfeff,stroke:#0369a1,color:#0f172a,stroke-width:1px;
    classDef analytics fill:#f5f3ff,stroke:#7c3aed,color:#4c1d95,stroke-width:1px;
    classDef demo fill:#fef2f2,stroke:#b91c1c,color:#7f1d1d,stroke-width:1px;
    classDef guard fill:#f1f5f9,stroke:#1e293b,color:#0f172a,stroke-width:1px;

    lint[Lint & static checks]:::base --> hgm[HGM guardrails]:::guard
    lint --> ownerCtl[Owner control assurance]:::guard
    tests[Tests]:::base --> foundry[Foundry]:::base
    tests --> coverage[Coverage thresholds]:::base
    tests --> invariants[Invariant tests]:::guard
    tests --> demos[Phase + demo suites]:::demo
    pyUnit[Python unit tests]:::analytics --> pyCov[Python coverage enforcement]:::analytics
    pyInt[Python integration tests]:::analytics --> pyCov
    pyLoad[Load-simulation reports]:::analytics --> summary[CI summary]:::guard
    branchGuard[Branch protection guard]:::guard --> summary
    foundry --> summary
    coverage --> summary
    invariants --> summary
    hgm --> summary
    ownerCtl --> summary
    demos --> summary
    pyCov --> summary
    lint --> summary
    tests --> summary

CI telemetry feed & dashboards

flowchart LR
    classDef artefact fill:#ecfeff,stroke:#0369a1,color:#0f172a,stroke-width:1px;
    classDef cli fill:#f5f3ff,stroke:#7c3aed,color:#4c1d95,stroke-width:1px;
    classDef surface fill:#f1f5f9,stroke:#1e293b,color:#0f172a,stroke-width:1px;

    summaryJob[ci (v2) / CI summary]:::cli --> statusJson[reports/ci/status.json]:::artefact
    summaryJob --> statusMarkdown[reports/ci/status.md]:::artefact
    statusJson --> dashboards[Mission dashboards\n& release control rooms]:::surface
    statusMarkdown --> briefings[Owner briefings\n& PR threads]:::surface
    cliProbe[npm run ci:status-wall]:::cli --> statusJson

• reports/ci/status.json exposes a machine-readable feed of the latest CI lattice; it is generated in every run and uploaded as an artefact so dashboards and compliance monitors can subscribe without scraping GitHub. (ci.yml)
• reports/ci/status.md mirrors the JSON feed in Markdown for direct inclusion in release notes, investor updates, or PR discussions. (ci.yml)
• npm run ci:status-wall -- --token <github_token> --require-success --include-companion --format json fetches the same data from the GitHub API on demand, giving mission owners and release captains a deterministic way to gate deployments or cut dashboards from their local terminal. Swap in --format markdown to reproduce the README tables programmatically. (check-ci-status-wall.ts)
• The artefacts capture the full badge wall, including fork bypass annotations, so anyone consuming the feed has the same visibility as the GitHub checks tab without needing repo admin permissions. (ci.yml)

Required contexts

The branch protection rule enforces the following ci (v2) contexts, guaranteeing a visible, fully green wall before merge:

Companion workflows are also required (static-analysis, fuzz, webapp, containers, e2e), guaranteeing the checks tab mirrors the entire assurance surface. (required-companion-contexts.json)

Companion workflow lattice

flowchart TD
    classDef main fill:#ecfeff,stroke:#0284c7,color:#0f172a,stroke-width:1px;
    classDef companion fill:#fef3c7,stroke:#d97706,color:#7c2d12,stroke-width:1px;
    classDef checks fill:#f1f5f9,stroke:#1e293b,color:#0f172a,stroke-width:1px;

    ciSummary[ci (v2) / CI summary]:::main --> checksWall[GitHub checks wall]:::checks
    staticAnalysis[static-analysis / Slither static analysis]:::companion --> checksWall
    fuzzSuite[fuzz / forge-fuzz]:::companion --> checksWall
    webappCi[webapp / webapp-ci]:::companion --> checksWall
    containersNode[containers / build (node-runner)]:::companion --> checksWall
    containersValidator[containers / build (validator-runner)]:::companion --> checksWall
    containersGateway[containers / build (gateway)]:::companion --> checksWall
    containersWebapp[containers / build (webapp)]:::companion --> checksWall
    containersOwner[containers / build (owner-console)]:::companion --> checksWall
    e2eSuite[e2e / orchestrator-e2e]:::companion --> checksWall

The manifest in ci/required-companion-contexts.json marks every companion workflow as required so the PR checks wall cannot go green unless they all pass beside the ci (v2) contexts, and npm run ci:verify-companion-contexts fails if the manifest drifts from GitHub's configuration. (required-companion-contexts.json) (package.json)

Branch protection autopilot

flowchart LR
    classDef manifest fill:#ecfdf5,stroke:#10b981,color:#064e3b,stroke-width:1px;
    classDef guard fill:#f1f5f9,stroke:#1e293b,color:#0f172a,stroke-width:1px;
    classDef summary fill:#eff6ff,stroke:#2563eb,color:#1e3a8a,stroke-width:1px;

    manifestDeck[ci/required-contexts.json\nci/required-companion-contexts.json]:::manifest --> branchGuard[ci (v2) / Branch protection guard]:::guard
    branchGuard --> githubAPI[GitHub Branch Protection API\n(enforced contexts)]:::guard
    branchGuard --> ciSummary[ci (v2) / CI summary]:::summary
    ciSummary --> checksTab[Protected branch checks wall]:::summary

Run the manifest + enforcement bundle whenever you add or rename CI jobs to keep PRs and main locked to the green wall:

The ci (v2) / Branch protection guard job re-runs step 4 inside every workflow execution and writes a bypass notice when forks lack administrative scopes, while the ci (v2) / CI summary job fails the run if any required job or artefact is missing—ensuring the enforcement wall is both visible and blocking. (ci.yml)

CI badge wall (ci (v2))

The badge query filters directly on the workflow run logs, so PR reviewers and release captains can confirm the fully green wall without leaving the repository homepage. Each job corresponds to the required contexts enumerated below and enforced by branch protection. (ci.yml) (required-contexts.json)

Enforcing branch protection

1. Generate or refresh required contexts:

   npm run ci:sync-contexts -- --check
   npm run ci:verify-contexts
   npm run ci:verify-companion-contexts

   Use npm run ci:sync-contexts (without --check) if you add or rename CI jobs; it rewrites the manifest deterministically and fails when duplicates slip in. (package.json) (update-ci-required-contexts.ts)
2. Audit the live rule without mutations:

   npm run ci:enforce-branch-protection -- --dry-run --branch main

3. Verify the GitHub rule via the public API without mutating anything (requires a fine-grained PAT or GitHub App token with administration:read scope):

   GITHUB_TOKEN=<token> npm run ci:verify-branch-protection -- --owner MontrealAI --repo AGIJobsv0 --branch main

   The script confirms the live protection rule matches ci/required-contexts.json and ci/required-companion-contexts.json, failing if the GitHub configuration is stale or missing contexts. (package.json) (verify-branch-protection.ts)
4. Apply the rule (requires repo admin token):

   npm run ci:enforce-branch-protection -- --branch main

   The branch protection guard job revalidates these expectations on every push to main, keeping policy and automation in sync while gracefully bypassing forked PRs that lack administrative scope. (package.json) (ci.yml)

Artefacts

• reports/ci/status.{md,json} – machine-readable run summaries consumed by release captains and compliance audits. (ci.yml)
• reports/owner-control/** – authority matrices, doctor reports, command-center digest, and parameter plans proving owner command coverage. (ci.yml)
• reports/load-sim/** – Monte Carlo CSV + JSON payloads with economic dissipation analysis. (ci.yml)

Architecture panorama

flowchart TD
    classDef ops fill:#f5f3ff,stroke:#7c3aed,color:#4c1d95,stroke-width:1px;
    classDef core fill:#ecfeff,stroke:#0284c7,color:#0f172a,stroke-width:1px;
    classDef demos fill:#fef2f2,stroke:#b91c1c,color:#7f1d1d,stroke-width:1px;
    classDef obs fill:#f1f5f9,stroke:#1e293b,color:#0f172a,stroke-width:1px;

    Owners((Mission Owners)):::ops --> OwnerPlane[Owner Control Plane]:::ops
    OwnerPlane --> Contracts[[Solidity Kernel + Modules]]:::core
    Contracts --> Services[[Agent Gateway & Services]]:::core
    Services --> Apps[[Operator / Validator Apps]]:::core
    Services --> Demos[[Strategic Demos]]:::demos
    Contracts --> Observability[[Sentinel, Thermostat, Load Sims]]:::obs
    Observability --> CI[[CI v2 + Companion Workflows]]:::obs
    CI --> Owners
    Demos --> Observability

Documentation & support

• OperatorRunbook.md – live incident and escalation procedures for mission owners.
• RUNBOOK.md – consolidated runbooks for validators, agents, and deployment captains.
• SECURITY.md – disclosure policy, threat model, and contact instructions.
• docs/user-guides/ – curated mission guides that plug directly into the owner control plane.
• ci/ – detailed CI v2 manifest, branch protection checklist, and verification commands.

License

Released under the MIT License. See LICENSE for details.