operator.json

{
  "schema_version": "operator.v0",
  "name": "pack",
  "version": "0.5.0",
  "description": "Standalone sealing entrypoint for lockfiles, reports, rules, and registry artifacts",
  "repository": "https://github.com/cmdrvl/pack",
  "license": "MIT",
  "agent_guide": "https://github.com/cmdrvl/.github/blob/main/profile/AGENT_PROMPT.md",

  "invocation": {
    "binary": "pack",
    "usage": [
      "pack seal <LOCKFILE> [<ARTIFACTS>...] [--output <DIR>] [--note <TEXT>] [--created <RFC3339>] [--outcome <TAG>] [--no-witness]",
      "pack verify <PACK_DIR> [--json] [--no-witness]",
      "pack inspect <PACK_DIR> [--json]",
      "pack diff <PACK_A> <PACK_B> [--json]",
      "pack archive export <PACK_DIR> --out <FILE>",
      "pack archive import <ARCHIVE> --out <DIR>",
      "pack witness <query|last|count> [OPTIONS]",
      "pack --robot-triage",
      "pack capabilities --json",
      "pack robot-docs guide",
      "pack doctor health [--json]",
      "pack doctor capabilities --json",
      "pack doctor robot-docs",
      "pack doctor --robot-triage",
      "pack doctor --fix"
    ],
    "output_mode": "mixed",
    "output_schema": "pack.v0",
    "json_flag": "--json"
  },

  "arguments": [],

  "options": [
    { "name": "no_witness", "flag": "--no-witness", "type": "flag", "description": "Suppress witness ledger recording" },
    { "name": "describe", "flag": "--describe", "type": "flag", "description": "Print compiled operator.json and exit 0" },
    { "name": "schema", "flag": "--schema", "type": "flag", "description": "Print pack.v0 JSON Schema and exit 0" },
    { "name": "robot_triage", "flag": "--robot-triage", "type": "flag", "description": "Emit read-only machine triage JSON and exit 0" },
    { "name": "version", "flag": "--version", "type": "flag", "description": "Print version and exit 0" }
  ],

  "subcommands": [
    {
      "name": "seal",
      "description": "Standalone sealing interface for artifacts already on disk",
      "options": [
        { "name": "output", "flag": "--output", "type": "path", "description": "Output directory; defaults to ~/.cmdrvl/state/pack/<pack_id>/" },
        { "name": "note", "flag": "--note", "type": "string", "description": "Optional annotation embedded in manifest" },
        { "name": "created", "flag": "--created", "type": "RFC3339", "description": "Reproducible manifest creation timestamp; takes precedence over SOURCE_DATE_EPOCH" },
        { "name": "outcome", "flag": "--outcome", "type": "string", "description": "Optional canonical outcome anchor (cmdrvl://...) embedded in manifest and pack_id" }
      ],
      "exit_codes": {
        "0": { "meaning": "PACK_CREATED", "domain": "positive" },
        "2": { "meaning": "REFUSAL", "domain": "error" }
      }
    },
    {
      "name": "verify",
      "description": "Verify pack integrity (members + pack_id)",
      "exit_codes": {
        "0": { "meaning": "OK", "domain": "positive" },
        "1": { "meaning": "INVALID", "domain": "negative" },
        "2": { "meaning": "REFUSAL", "domain": "error" }
      }
    },
    {
      "name": "inspect",
      "description": "Read pack metadata without verifying integrity",
      "status": "implemented",
      "witness": "not_recorded",
      "exit_codes": {
        "0": { "meaning": "METADATA", "domain": "positive" },
        "2": { "meaning": "REFUSAL", "domain": "error" }
      }
    },
    {
      "name": "diff",
      "description": "Deterministically diff two packs",
      "status": "implemented",
      "exit_codes": {
        "0": { "meaning": "NO_CHANGES", "domain": "positive" },
        "1": { "meaning": "CHANGES", "domain": "negative" },
        "2": { "meaning": "REFUSAL", "domain": "error" }
      }
    },
    {
      "name": "archive",
      "description": "Export/import deterministic tar wrappers around canonical pack directories",
      "status": "implemented",
      "witness": "not_recorded",
      "exit_codes": {
        "0": { "meaning": "ARCHIVE_CREATED or ARCHIVE_IMPORTED", "domain": "positive" },
        "2": { "meaning": "REFUSAL", "domain": "error" }
      }
    },
    {
      "name": "witness",
      "description": "Query witness ledger",
      "exit_codes": {
        "0": { "meaning": "OK", "domain": "positive" },
        "2": { "meaning": "REFUSAL", "domain": "error" }
      }
    },
    {
      "name": "capabilities",
      "description": "Read-only machine-readable agent capability contract",
      "status": "implemented",
      "read_only": true,
      "witness": "not_recorded",
      "commands": [
        "pack capabilities --json"
      ],
      "exit_codes": {
        "0": { "meaning": "CAPABILITIES", "domain": "positive" }
      }
    },
    {
      "name": "robot-docs",
      "description": "Read-only agent operating guide",
      "status": "implemented",
      "read_only": true,
      "witness": "not_recorded",
      "commands": [
        "pack robot-docs guide"
      ],
      "exit_codes": {
        "0": { "meaning": "ROBOT_DOCS", "domain": "positive" }
      }
    },
    {
      "name": "doctor",
      "description": "Read-only diagnostics for agents and operators",
      "status": "implemented",
      "read_only": true,
      "witness": "not_recorded",
      "fix_mode": "not_available",
      "commands": [
        "pack doctor health",
        "pack doctor health --json",
        "pack doctor capabilities --json",
        "pack doctor robot-docs",
        "pack doctor --robot-triage",
        "pack doctor --fix"
      ],
      "side_effects": {
        "reads_pack_inputs": false,
        "reads_pack_members": false,
        "walks_pack_dirs": false,
        "seals_packs": false,
        "verifies_pack_integrity": false,
        "diffs_pack_dirs": false,
        "exports_archives": false,
        "imports_archives": false,
        "writes_witness_ledger": false,
        "creates_witness_directory": false,
        "writes_doctor_artifacts": false,
        "rewrites_operator_manifest": false,
        "rewrites_schema": false,
        "uses_network": false
      },
      "exit_codes": {
        "0": { "meaning": "DOCTOR_OK", "domain": "positive" },
        "2": { "meaning": "CLI_USAGE", "domain": "error" }
      }
    }
  ],

  "exit_codes": {
    "0": { "meaning": "SUCCESS", "domain": "positive" },
    "1": { "meaning": "INVALID or CHANGES", "domain": "negative" },
    "2": { "meaning": "REFUSAL", "domain": "error" }
  },

  "refusals": [
    { "code": "E_EMPTY", "message": "Seal called with no artifacts", "action": "escalate" },
    { "code": "E_IO", "message": "Cannot read input, write output, or read pack directory", "action": "escalate" },
    { "code": "E_DUPLICATE", "message": "Member path collision during seal (including reserved paths)", "action": "escalate" },
    { "code": "E_BAD_PACK", "message": "Missing or invalid manifest.json for verify/diff/archive", "action": "escalate" }
  ],

  "capabilities": {
    "formats": ["*"],
    "profile_aware": false,
    "streaming": false,
    "witness": {
      "ambient_recording": "enabled_by_default",
      "query_subcommands": true,
      "no_witness_flag": "suppresses_recording"
    },
    "doctor": {
      "read_only": true,
      "robot_triage": true,
      "top_level_surfaces": [
        "pack --robot-triage",
        "pack capabilities --json",
        "pack robot-docs guide"
      ],
      "fix_mode": "not_available"
    }
  },

  "pipeline": {
    "upstream": ["lock", "canon", "rvl"],
    "downstream": []
  }
}