Add an optional AISP deployment readiness contract for eval, approval, deploy, rollback, and observability gates

Bắt đầu bằng cách đọc skills/google-agents-cli-deploy/SKILL.md và kiểm tra entry point deploy hiện có, các test và cấu trúc eval. Sử dụng package aisp/ được đề xuất và layout evals/deploy-readiness-traces/ làm phạm vi tham chiếu, sau đó xác định cách một báo cáo readiness có cấu trúc và tùy chọn có thể bao quát các gate được liệt kê mà không thay đổi hành vi deploy cục bộ. Công việc được xem là hoàn tất khi các gate của MVP, phần tóm tắt phê duyệt, đầu ra của báo cáo và các test cho sự mơ hồ của target, eval bị bỏ qua, sự không khớp của Python và thiếu metadata rollback đã được xác định.

What is your feature suggestion?

Add an optional machine-readable deployment readiness contract for agents-cli deploy.

The deploy skill already covers high-risk production concerns: Agent Runtime, Cloud Run, GKE, CI/CD, secrets, service accounts, status polling, and explicit human approval. I propose adding an optional AISP V1.0.0 companion package that captures the deploy readiness gates as a structured contract.

AISP protocol reference:

https://github.com/AIXP-Labs/AISP

The goal is not to replace the deploy skill.

The goal is to make deployment gates testable and auditable.

Possible layout:

skills/google-agents-cli-deploy/
├── SKILL.md
└── aisp/
    └── google_agents_cli_deploy_readiness_aisp/
        ├── aisp.aisop.json
        ├── README.md
        └── evals/
            └── deploy-readiness-traces/

A standard AISP V1.0.0 package could look like this:

[
  {
    "role": "system",
    "content": {
      "protocol": "AISP V1.0.0",
      "axiom_0": "Human_Sovereignty_and_Wellbeing",
      "id": "google_agents_cli_deploy_readiness_aisp",
      "name": "Google Agents CLI Deploy Readiness Contract",
      "version": "1.0.0",
      "license": "Apache-2.0",
      "summary": "A machine-checkable deployment readiness contract for agents-cli deploy.",
      "description": "Defines eval, docs, project, IAM, secrets, Python version, human approval, deploy, rollback, and observability gates before and after deploying ADK agents to Google Cloud targets.",
      "flow_format": "mermaid",
      "loading_mode": "node",
      "tools": [
        "filesystem",
        "shell",
        "network"
      ],
      "params": {
        "project_root": "string",
        "deployment_target": "string",
        "gcp_project": "string?",
        "region": "string?",
        "python_version": "string?"
      },
      "system_prompt": ""
    }
  },
  {
    "role": "user",
    "content": {
      "instruction": "STRICTLY OBEY aisp_contract; its non_negotiable rules are inviolable; then RUN aisop.main",
      "user_input": "{user_input}",
      "aisp_contract": {
        "profile": "aisp.skill.v1",
        "invocation": {
          "mode": "deployment_readiness",
          "when_to_use": [
            "before running agents-cli deploy",
            "before deploying to Agent Runtime, Cloud Run, or GKE",
            "before publishing a deployment for shared or production use",
            "when deployment involves Google Cloud resources, service accounts, secrets, or public endpoints"
          ],
          "when_not_to_use": [
            "local-only agent run",
            "read-only deploy status check",
            "dry-run that writes no cloud resources"
          ]
        },
        "non_negotiable": [
          {
            "rule": "Do not deploy without explicit human approval.",
            "enforced_by": "approval.step2:sys.io.confirm"
          },
          {
            "rule": "Do not deploy before eval status is recorded or explicit no-eval approval exists.",
            "enforced_by": "eval_gate.step3:sys.assert"
          },
          {
            "rule": "Do not deploy if deployment target, project, or region is ambiguous.",
            "enforced_by": "target_gate.step3:sys.assert"
          },
          {
            "rule": "Do not silently use CLI Python as remote build Python when project metadata declares a different supported range.",
            "enforced_by": "python_gate.step3:sys.assert"
          },
          {
            "rule": "Do not deploy secrets as plain environment variables when Secret Manager or equivalent managed secret path is required.",
            "enforced_by": "secrets_gate.step2:sys.assert"
          },
          {
            "rule": "Do not mark deployment complete until endpoint/status metadata and post-deploy validation are recorded.",
            "enforced_by": "post_deploy.step3:sys.assert"
          },
          {
            "rule": "Do not skip rollback notes for production/shared deployments.",
            "enforced_by": "rollback.step2:sys.assert"
          },
          {
            "rule": "Do not skip observability status for production/shared deployments.",
            "enforced_by": "observe.step2:sys.assert"
          }
        ],
        "discovery": {
          "category": "deployment",
          "tags": [
            "agents-cli",
            "deploy",
            "agent-runtime",
            "cloud-run",
            "gke",
            "eval",
            "rollback",
            "observability",
            "aisp"
          ]
        },
        "risk_level": "high",
        "resources": [
          {
            "id": "project_root",
            "path": "{project_root}",
            "kind": "repository",
            "mode": "read_only",
            "when": "Read before deployment readiness checks.",
            "scope": "skill"
          },
          {
            "id": "deploy_trace",
            "path": "evals/deploy-readiness-traces/",
            "kind": "trace_dir",
            "mode": "read_write",
            "when": "Write after deployment readiness check and deploy attempt.",
            "scope": "skill"
          }
        ]
      },
      "aisop": {
        "main": "graph TD\n    target_gate[Resolve target project and region] --> docs_gate[Verify deployment docs]\n    docs_gate --> eval_gate[Check eval status]\n    eval_gate --> python_gate[Check Python/build compatibility]\n    python_gate --> iam_gate[Check IAM and service account]\n    iam_gate --> secrets_gate[Check secrets handling]\n    secrets_gate --> approval[Ask human approval]\n    approval --> deploy[Deploy]\n    deploy --> post_deploy[Post-deploy validation]\n    post_deploy --> rollback[Record rollback path]\n    rollback --> observe[Verify observability]\n    observe --> trace[Write deploy readiness trace]\n    trace --> end_node((End))"
      },
      "functions": {
        "target_gate": {
          "step1": "Resolve deployment target, GCP project, region, service/account context, and endpoint exposure.",
          "step2": "Compare resolved target with manifest and CLI flags.",
          "step3": "sys.assert('deployment target project and region are unambiguous', 'Deployment target/project/region ambiguity must be resolved')",
          "output_mapping": "deployment_target_status"
        },
        "docs_gate": {
          "step1": "Verify official deployment docs relevant to target and API version.",
          "output_mapping": "deployment_docs_status"
        },
        "eval_gate": {
          "step1": "Check eval results, skipped reason, or explicit no-eval approval.",
          "step2": "Record threshold status if thresholds are configured.",
          "step3": "sys.assert('eval status recorded before deployment', 'Eval gate required before deployment')",
          "output_mapping": "eval_gate_status"
        },
        "python_gate": {
          "step1": "Read project Python metadata and selected remote build Python.",
          "step2": "Check compatibility with project constraints and dependencies.",
          "step3": "sys.assert('remote build Python compatible and not silently CLI-derived', 'Deployment Python version gate failed')",
          "output_mapping": "python_build_status"
        },
        "iam_gate": {
          "step1": "Check service account, required roles, and auth mode.",
          "output_mapping": "iam_status"
        },
        "secrets_gate": {
          "step1": "Check secret handling for deployment target.",
          "step2": "sys.assert('secrets use managed secret path when required', 'Secrets handling is unsafe for deployment target')",
          "output_mapping": "secrets_status"
        },
        "approval": {
          "step1": "Summarize target, project, region, eval status, IAM, secrets, estimated impact, and rollback path.",
          "step2": "sys.io.confirm('Proceed with deployment?') -> deploy_approved",
          "output_mapping": "approval_status"
        },
        "deploy": {
          "step1": "Run deployment only if deploy_approved is true.",
          "output_mapping": "deploy_attempt"
        },
        "post_deploy": {
          "step1": "Poll status or check deployed endpoint as appropriate.",
          "step2": "Run a minimal health check or status validation.",
          "step3": "sys.assert('post-deploy metadata and validation recorded', 'Deployment completion requires validation metadata')",
          "output_mapping": "post_deploy_status"
        },
        "rollback": {
          "step1": "Record rollback command or rollback strategy.",
          "step2": "sys.assert('rollback path recorded for production/shared deployment', 'Rollback path required')",
          "output_mapping": "rollback_status"
        },
        "observe": {
          "step1": "Check Cloud Trace/logging/observability status where relevant.",
          "step2": "sys.assert('observability status recorded for production/shared deployment', 'Observability status required')",
          "output_mapping": "observability_status"
        },
        "trace": {
          "step1": "Write deployment readiness trace with all gate results and final deployment status.",
          "output_mapping": "deploy_readiness_trace"
        },
        "end_node": {
          "step1": "Return deploy_readiness_trace."
        }
      }
    }
  }
]

What will this enable you to do?

This would make high-risk deploy workflows easier to debug and safer to delegate to coding agents.

It would enable:

• consistent deploy readiness checks across targets;
• explicit eval status before deployment;
• explicit human approval with a clear summary;
• traceable target/project/region selection;
• safer Python build version handling;
• clearer IAM and secrets checks;
• auditable post-deploy validation;
• deploy trace artifacts that can be used in CI or support debugging.

It would also reduce ambiguous failure modes where the coding agent deploys using implicit defaults or stale assumptions.

Additional context

This can start as docs + tests + optional trace output.

Non-goals:

• Do not replace agents-cli deploy.
• Do not require AISP runtime support.
• Do not block local development.
• Do not force users to configure every gate for simple local use.
• Do not replace Google Cloud IAM/Secret Manager/deployment mechanisms.

MVP:

1. Define deploy readiness gate names.
2. Emit a structured deploy readiness report.
3. Require explicit human approval with target/project/region/eval summary.
4. Add tests for target ambiguity, eval skipped, Python mismatch, and missing rollback metadata.
5. Optionally include the AISP artifact as a reference contract.