acdl/docs/submission-readiness.md

Submission Readiness — What is Acceptable to Start

Source of truth: schemas/submission-readiness.schema.json (v1.18, REQ-217). The validator is core/submission_readiness.py (REQ-218), invoked as python3 -m core.lambda.contract_ingestor --check-readiness <submission.json> (D-133).

Nova's submission-readiness gate defines what is acceptable to start. It is a superset gate above contract-schema validity: the contract schema (schemas/contract.schema.json) defines the shape (id / name / environment / infrastructure); the readiness schema defines the gate (tags, per-env mandatory metadata, policy preconditions, profile markers, appSource). Both must pass before ingestion proceeds.

How It Works

citizen developer submits
        ↓
contract.schema.json validation (shape)     ← the existing check
        ↓
submission-readiness.schema.json (gate)     ← the new check
  ├── contractId present (non-empty)
  ├── environment valid (dev/qa/prod/dr)
  ├── tags: all 5 Nova tags present (D-054)
  ├── policyPreconditions declared
  ├── profile: developer or agentic
  │     └── if agentic: naturalLanguageIntent + confidenceAtSubmission + agentTrace
  ├── appSource: repo + ref (for runtime fetch)
  └── per-env mandatory (W3.E):
        dev  → stack + environment
        qa   → + validation.e2eSuite + validation.loadTest
        prod → + runbook + dashboard + oncall
        dr   → + drDrillRef
        ↓
ready → proceed to contract ingestion
not ready → reject with citizen-developer-facing error (reason code)

Reason Codes

When a submission is not ready, the validator returns one or more reason codes. These are citizen-developer-facing — no stack traces.

Code	Meaning
MISSING_TAGS:<tag1>,<tag2>	One or more required Nova tags are absent
ENV_MISSING_MANDATORY:<env>:<field>	A per-env mandatory field (W3.E) is missing
AGENTIC_MISSING_INTENT:<marker>	profile=agentic but a required marker is absent
MISSING_APP_SOURCE	appSource (repo + ref) is missing
POLICY_PRECONDITION_MISSING	No policy preconditions declared
CONTRACT_SCHEMA_INVALID:<detail>	The contract shape failed contract.schema.json
READINESS_SCHEMA_INVALID:<detail>	The submission failed the readiness schema

Good Example

{
  "contractId": "uuid-1234",
  "id": "webapi",
  "name": "Customer Web API",
  "environment": "dev",
  "tags": {
    "nova:owner": "consumer-repo",
    "nova:contract": "uuid-1234",
    "nova:environment": "dev",
    "nova:cost-center": "nova-default",
    "nova:ref": "CHG0678912"
  },
  "policyPreconditions": {
    "public-ingress": false,
    "encryption_enabled": true,
    "deletion_protection": true
  },
  "profile": "developer",
  "appSource": {
    "repo": "consumer/web-api",
    "ref": "main"
  },
  "infrastructure": {
    "static-assets": {
      "inputs": {
        "bucket_name": "webapi-assets"
      }
    }
  }
}

Result: READY — passes the shape + the gate.

Rejected Examples

Missing Tags

{
  "contractId": "uuid-1234",
  "environment": "dev",
  "tags": {
    "nova:owner": "consumer-repo"
  },
  "policyPreconditions": {"public-ingress": false},
  "profile": "developer",
  "appSource": {"repo": "consumer/repo", "ref": "main"}
}

Result: NOT READY — MISSING_TAGS:nova:contract,nova:environment,nova:cost-center,nova:ref

Agentic Missing Intent

{
  "contractId": "uuid-1234",
  "environment": "qa",
  "tags": { "nova:owner": "x", "nova:contract": "x", "nova:environment": "qa", "nova:cost-center": "x", "nova:ref": "x" },
  "policyPreconditions": {"public-ingress": false},
  "profile": "agentic",
  "appSource": {"repo": "x", "ref": "x"},
  "validation": {"e2eSuite": true, "loadTest": true}
}

Result: NOT READY — AGENTIC_MISSING_INTENT:naturalLanguageIntent; AGENTIC_MISSING_INTENT:confidenceAtSubmission; AGENTIC_MISSING_INTENT:agentTrace

Env Missing Mandatory (prod without runbook)

{
  "contractId": "uuid-1234",
  "environment": "prod",
  "tags": { "nova:owner": "x", "nova:contract": "x", "nova:environment": "prod", "nova:cost-center": "x", "nova:ref": "x" },
  "policyPreconditions": {"public-ingress": false},
  "profile": "developer",
  "appSource": {"repo": "x", "ref": "x"}
}

Result: NOT READY — ENV_MISSING_MANDATORY:prod:runbook; ENV_MISSING_MANDATORY:prod:dashboard; ENV_MISSING_MANDATORY:prod:oncall

Compliance-Standard Equivalence

The submission-readiness gate applies equally to all upstream sources. Whether the citizen developer's submission originated from an AI coding agent, an agentic SDLC platform, or a traditional development platform — the same tags, the same env mandatory, the same policy preconditions, the same profile markers are required. The source does not matter; the submission does. This is the RACI compliance-standard equivalence note (docs/raci.md) made machine-checkable.