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

### 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:

```text
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:

```json
[
{
"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.

Beginne mit dem Lesen von skills/google-agents-cli-deploy/SKILL.md und untersuche den bestehenden Deployment-Einstiegspunkt, die Tests und die Eval-Struktur. Verwende das vorgeschlagene aisp/-Paket und das Layout evals/deploy-readiness-traces/ als Referenzumfang und ermittle anschließend, wie ein optionaler strukturierter Readiness-Bericht die aufgeführten Gates abdecken kann, ohne das lokale Deployment-Verhalten zu ändern. Erledigt ist die Aufgabe, wenn die MVP-Gates, die Genehmigungszusammenfassung, die Berichtsausgabe und Tests für Zielmehrdeutigkeit, übersprungene Evals, Python-Abweichungen und fehlende Rollback-Metadaten definiert sind.

Vom Indexierungsmodell aus dem Issue-Text verfasst.