Schema reference

Complete field-by-field reference for devcontract.json. The schema has eight clause families. All clauses except stack, cost, security, and definition_of_done are optional — include only what applies to your engagement.

Top-level fields

Field	Type	Required	Description
`contract_version`	string	Yes	Schema version. Currently `"1.0"`.
`project`	string	Yes	Project name. Appears in the rendered steering block and evidence bundle.
`parties`	object	Yes	The parties to the contract. See below.
`stack`	object	Yes	Language, runtime, region, forbidden services.
`cost`	object	Yes	Budget envelope and forbidden resources.
`security`	object	Yes	Auth mechanism, secrets store, and deployment gates.
`quality`	object	No	Type hints, coverage, logging, forbidden code patterns.
`architecture`	object	No	Required and forbidden architectural patterns.
`compliance`	object	No	Regulatory frameworks and data handling requirements.
`audit`	object	No	Evidence requirements and retention.
`definition_of_done`	object	Yes	Acceptance criteria including scan gates.

parties

Field	Type	Default	Description
`client`	string	—	The client identity — your name, team name, or organisation.
`contractor`	string	`"claude-code"`	The AI contractor identity. Appears in the evidence bundle.

stack

Field	Type	Required	Description
`language`	string	Yes	Primary language. e.g. `"python"`, `"typescript"`.
`language_version`	string	Yes	Required language version. e.g. `"3.12"`.
`runtime`	string	Yes	Execution runtime. e.g. `"aws_lambda"`, `"node"`, `"container"`.
`region`	string	Yes	Primary cloud region. e.g. `"eu-north-1"`.
`forbidden_services`	string[]	No	Cloud services the AI must never suggest or use. e.g. `["ec2", "fargate", "rds"]`.

architecture

Field	Type	Description
`required_patterns`	string[]	Architectural patterns the AI must use. e.g. `["single_table_dynamodb", "handler_delegates_to_domain"]`.
`forbidden_patterns`	string[]	Patterns the AI must never introduce. e.g. `["fat_handler", "orm_layer", "god_class"]`.
`module_boundaries`	object	Map of filename to responsibility. e.g. `{"handler.py": "routing_only", "db.py": "data_access_only"}`.
`review_gate`	string \| null	If set, major architectural decisions require this approval. e.g. `"architecture_board_required"`.

cost

Field	Type	Required	Description
`budget_envelope`	string	Yes	Named budget tier. e.g. `"aws_free_tier"`, `"business"`, `"enterprise"`.
`forbidden_resources`	string[]	No	AWS/cloud resource types that must never be created. e.g. `["nat_gateway", "rds", "secrets_manager", "kms_cmk"]`.
`approved_exceptions`	string[]	No	Explicit exceptions to the budget envelope with documented rationale. e.g. `["route53_hosted_zone"]`.

security

Field	Type	Required	Description
`auth_mechanism`	string	Yes	Required authentication approach. e.g. `"cognito_jwt"`, `"oidc_saml"`, `"mfa_required"`.
`secrets_store`	string	Yes	Where secrets must live. e.g. `"ssm_parameter_store"`, `"aws_secrets_manager"`.
`forbidden_secrets_locations`	string[]	No	Where secrets must never appear. e.g. `["env_vars", "source_code", "config_files"]`.
`pii_handling`	string \| null	No	PII policy. e.g. `"redact_before_llm"`.
`owasp_compliance`	boolean	No	Whether OWASP Top 10 compliance is required. Defaults to `true`.
`production_deploy_gate`	boolean	No	If `true`, production deployment requires human approval. Defaults to `true`.
`pen_test_gate`	boolean	No	If `true`, a penetration test is required before production. Defaults to `false`.

quality

Field	Type	Default	Description
`type_hints`	`"required"` \| `"recommended"` \| `"optional"`	`"required"`	Type annotation requirement for all function signatures.
`docstrings`	`"all"` \| `"public_only"` \| `"optional"`	`"public_only"`	Docstring requirement.
`test_coverage_min`	integer	`80`	Minimum test coverage percentage.
`logging_standard`	string	`"module_logger_only"`	Logging approach. `"module_logger_only"` means `logging.getLogger(__name__)` — never `print()`.
`forbidden_patterns`	string[]	`[]`	Code patterns the AI must never write. e.g. `["print_statements", "bare_except", "mutable_defaults"]`.

compliance

Field	Type	Description
`frameworks`	string[]	Regulatory frameworks in force. e.g. `["gdpr"]`, `["gdpr", "iso27001"]`, `["iso27001", "cyber_essentials"]`.
`data_classification`	boolean	If `true`, PII must be classified before any LLM processing.
`audit_trail`	boolean	If `true`, an immutable audit trail is required.
`right_to_erasure`	string \| null	Data deletion policy. `"hard_delete_only"` means soft-delete is forbidden.
`data_residency`	string \| null	Where data must reside. e.g. `"eu_only"`, `"uk_or_eu_only"`.
`change_management`	string \| null	Change management requirement. e.g. `"crq_required"` for enterprise/government.

audit

Field	Type	Default	Description
`evidence_required`	boolean	`true`	Whether an evidence bundle must be produced at delivery.
`evidence_format`	string	`"json"`	Evidence format. Currently only `"json"` is supported.
`evidence_signed`	boolean	`true`	Whether the evidence bundle must be SHA-256 signed against the contract hash.
`pr_comment_required`	boolean	`true`	Whether the evidence summary must be posted as a PR comment.
`retention_years`	integer \| null	`null`	How long evidence must be retained. Use `7` for regulated industries.
`findings_min_detail`	string	`"clause_level"`	Minimum granularity of evidence findings. `"clause_level"` means each clause must have a pass/fail result.

definition_of_done

Field	Type	Default	Description
`tests_pass`	boolean	`true`	All tests must pass.
`no_contract_violations`	boolean	`true`	No contract violations may be present at delivery.
`coverage_met`	boolean	`true`	Test coverage must meet the `quality.test_coverage_min` threshold.
`evidence_generated`	boolean	`true`	A signed evidence bundle must have been produced.
`security_scan_pass`	boolean	`true`	The Gatekeep security scan must pass.
`pr_comment_posted`	boolean	`true`	The evidence summary must be posted as a PR comment.
`pen_test_pass`	boolean	`false`	A penetration test must have passed. Enterprise/government only.
`dpo_review_gate`	boolean	`false`	DPO review is required. GDPR + regulated SaaS.
`accessibility_audit_pass`	boolean	`false`	An accessibility audit must have passed. Government/public sector.
`change_management_approved`	boolean	`false`	Change management approval must have been obtained.
`scan_gates`	ScanGate[]	`[]`	Gatekeep scan gates. See scan gates reference.

ScanGate object

Field	Type	Required	Description
`category`	string	Yes	Gatekeep finding category. One of: `governance`, `dependency`, `code_quality`, `security`, `iac`, `secret`, `sast`, `license`, `quality`.
`severity`	string	Yes	Minimum severity level to trigger this gate. One of: `critical`, `high`, `medium`, `low`, `info`.
`threshold`	integer	No	Maximum number of findings allowed at this severity. Default `0` — fail on any finding.
`blocking`	boolean	No	If `true`, exceeding the threshold blocks the PR. If `false`, advisory only. Default `true`.

Minimal example

{
  "contract_version": "1.0",
  "project": "my-python-api",
  "parties": {"client": "your-name", "contractor": "claude-code"},
  "stack": {
    "language": "python", "language_version": "3.12",
    "runtime": "aws_lambda", "region": "eu-north-1"
  },
  "cost": {
    "budget_envelope": "aws_free_tier",
    "forbidden_resources": ["nat_gateway", "rds", "secrets_manager"]
  },
  "security": {
    "auth_mechanism": "cognito_jwt",
    "secrets_store": "ssm_parameter_store"
  },
  "definition_of_done": {
    "tests_pass": true, "coverage_met": true,
    "scan_gates": [
      {"category": "secret", "severity": "critical", "blocking": true},
      {"category": "sast", "severity": "high", "blocking": true}
    ]
  }
}