Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 10 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -42,8 +42,9 @@ npm run validate

| Path | Purpose |
|------|---------|
| `schemas/v0.1/` | Authoritative JSON Schemas |
| `examples/v0.1/` | Complete executable lifecycle fixtures |
| `schemas/v0.1/` | Foundation lifecycle schemas retained for existing consumers |
| `schemas/v1.0/` | Bounded goal and lifecycle schemas |
| `examples/v0.1/`, `examples/v1.0/` | Complete executable lifecycle fixtures |
| `tests/` | Positive, negative, and lifecycle contract tests |
| `docs/VERSIONING.md` | Compatibility and evolution policy |
| `docs/DISTRIBUTION.md` | Stable and immutable schema registry URLs |
Expand All @@ -57,9 +58,15 @@ The schemas are public APIs. Review [versioning and compatibility](docs/VERSIONI

Released schemas are discoverable from `https://coding-autopilot-system.github.io/cas-contracts/index.json`. Use stable `vMAJOR.MINOR` URLs for compatible updates or immutable `releases/vMAJOR.MINOR.PATCH` URLs for reproducible builds. See [schema distribution](docs/DISTRIBUTION.md).

The v1 `WorkRequest` rejects dispatch unless objective, repositories,
measurable criteria, constraints, risk, approval and verification policies,
capabilities, bounded execution limits, and stop policy are explicit. Its
documented defaults are fan-out 3, iterations 3, attempts 3, runtime 1800
seconds, model calls 20, and no-progress limit 2.

## Status

`v0.1.0` is the useful foundation release. Compatibility automation and versioned registry distribution are available for subsequent releases.
`v0.1.0` remains the supported foundation line. `v1.0.0` adds the bounded goal contract as an explicit major-version opt-in.

## License

Expand Down
12 changes: 12 additions & 0 deletions docs/VERSIONING.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,18 @@ Major releases may remove or rename properties, add required properties, narrow
- Consumers should ignore unknown optional properties only when their validator policy permits them.
- Consumers must not infer compatibility solely from file paths; validate against the declared schema.

## v1.0 Goal Contract Migration

The v1.0 line introduces required bounded-goal properties on `WorkRequest`.
This is intentionally a major-version boundary: v0.1 schemas and payloads remain
published and valid, while producers opt into v1.0 by emitting
`schemaVersion: 1.0.0` and supplying success criteria, constraints, policies,
capabilities, budget limits, and stop policy.

Registry builds publish both stable lines. Consumers must select the schema ID
matching the record's explicit version; they must not validate a v0.1 payload
against v1.0 or silently synthesize missing limits.

## Change Procedure

Every contract change must include updated examples, tests, changelog entry, compatibility classification, and migration notes for breaking changes.
Expand Down
18 changes: 18 additions & 0 deletions examples/v1.0/artifact-manifest.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
{
"kind": "ArtifactManifest",
"correlationId": "corr-20260611-001",
"promptId": "prompt-001",
"runId": "run-001",
"repo": "Coding-Autopilot-System/cas-contracts",
"actor": { "id": "gsd-orchestrator", "type": "workflow" },
"timestamp": "2026-06-11T09:00:04Z",
"schemaVersion": "1.0.0",
"traceContext": { "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01" },
"artifacts": [
{
"kind": "schema",
"uri": "https://schemas.coding-autopilot.dev/v1.0/prompt-envelope.schema.json",
"sha256": "0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"
}
]
}
20 changes: 20 additions & 0 deletions examples/v1.0/evaluation-result.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,20 @@
{
"kind": "EvaluationResult",
"correlationId": "corr-20260611-001",
"promptId": "prompt-001",
"runId": "run-001",
"repo": "Coding-Autopilot-System/cas-contracts",
"actor": { "id": "cas-evals", "type": "service" },
"timestamp": "2026-06-11T09:00:06Z",
"schemaVersion": "1.0.0",
"traceContext": { "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01" },
"evaluator": "contract-completeness-v1",
"outcome": "passed",
"metrics": {
"schemaValidity": 1,
"traceability": 1
},
"evidence": [
{ "kind": "test-report", "uri": "cas://evidence/evaluation-001" }
]
}
14 changes: 14 additions & 0 deletions examples/v1.0/policy-decision.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
{
"kind": "PolicyDecision",
"correlationId": "corr-20260611-001",
"promptId": "prompt-001",
"runId": "run-001",
"repo": "Coding-Autopilot-System/cas-contracts",
"actor": { "id": "policy-engine", "type": "service" },
"timestamp": "2026-06-11T09:00:01Z",
"schemaVersion": "1.0.0",
"traceContext": { "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01" },
"decision": "allow",
"policyVersion": "2026.06",
"reasons": ["Requested paths are within the contract repository."]
}
14 changes: 14 additions & 0 deletions examples/v1.0/prompt-envelope.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
{
"kind": "PromptEnvelope",
"correlationId": "corr-20260611-001",
"promptId": "prompt-001",
"runId": "run-001",
"repo": "Coding-Autopilot-System/cas-contracts",
"actor": { "id": "kim", "type": "human", "displayName": "Repository owner" },
"timestamp": "2026-06-11T09:00:00Z",
"schemaVersion": "1.0.0",
"traceContext": { "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01" },
"intent": "Add a versioned lifecycle contract",
"prompt": "Define and validate the CAS lifecycle contracts.",
"constraints": ["No secrets in examples", "Preserve backward compatibility"]
}
15 changes: 15 additions & 0 deletions examples/v1.0/run-event.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
{
"kind": "RunEvent",
"correlationId": "corr-20260611-001",
"promptId": "prompt-001",
"runId": "run-001",
"repo": "Coding-Autopilot-System/cas-contracts",
"actor": { "id": "gsd-orchestrator", "type": "workflow" },
"timestamp": "2026-06-11T09:00:03Z",
"schemaVersion": "1.0.0",
"traceContext": { "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01" },
"eventType": "validation.started",
"sequence": 1,
"status": "running",
"message": "Validating lifecycle fixtures."
}
19 changes: 19 additions & 0 deletions examples/v1.0/verification-result.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,19 @@
{
"kind": "VerificationResult",
"correlationId": "corr-20260611-001",
"promptId": "prompt-001",
"runId": "run-001",
"repo": "Coding-Autopilot-System/cas-contracts",
"actor": { "id": "ci", "type": "service" },
"timestamp": "2026-06-11T09:00:05Z",
"schemaVersion": "1.0.0",
"traceContext": { "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01" },
"outcome": "passed",
"checks": [
{
"name": "contract-tests",
"outcome": "passed",
"evidenceUri": "https://github.com/Coding-Autopilot-System/cas-contracts/actions"
}
]
}
31 changes: 31 additions & 0 deletions examples/v1.0/work-request.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
{
"kind": "WorkRequest",
"correlationId": "corr-20260611-001",
"promptId": "prompt-001",
"runId": "run-001",
"repo": "Coding-Autopilot-System/cas-contracts",
"actor": { "id": "autogen", "type": "agent" },
"timestamp": "2026-06-11T09:00:02Z",
"schemaVersion": "1.0.0",
"traceContext": { "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01" },
"workType": "change",
"objective": "Publish and validate the bounded v1 goal contract.",
"targetRef": "refs/heads/main",
"targetRepositories": ["Coding-Autopilot-System/cas-contracts"],
"successCriteria": [
{ "id": "contracts-pass", "description": "All contract examples and negative validation tests pass." }
],
"constraints": ["Preserve all v0.1 payloads and schemas unchanged."],
"riskLevel": "medium",
"approvalPolicy": "risk-based",
"verificationProfile": "contracts-default",
"requiredCapabilities": ["json-schema", "node-test"],
"budget": {
"maxFanOut": 3,
"maxIterations": 3,
"maxAttemptsPerWorkItem": 3,
"maxRuntimeSeconds": 1800,
"maxModelCalls": 20
},
"stopPolicy": { "noProgressLimit": 2 }
}
31 changes: 31 additions & 0 deletions schemas/v1.0/artifact-manifest.schema.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,31 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://schemas.coding-autopilot.dev/v1.0/artifact-manifest.schema.json",
"title": "ArtifactManifest",
"type": "object",
"allOf": [
{
"$ref": "common.schema.json#/$defs/lifecycleMetadata"
},
{
"type": "object",
"required": [
"kind",
"artifacts"
],
"properties": {
"kind": {
"const": "ArtifactManifest"
},
"artifacts": {
"type": "array",
"minItems": 1,
"items": {
"$ref": "common.schema.json#/$defs/evidence"
}
}
}
}
],
"unevaluatedProperties": false
}
68 changes: 68 additions & 0 deletions schemas/v1.0/common.schema.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://schemas.coding-autopilot.dev/v1.0/common.schema.json",
"title": "CAS Common Definitions",
"$defs": {
"actor": {
"type": "object",
"additionalProperties": false,
"required": ["id", "type"],
"properties": {
"id": { "type": "string", "minLength": 1, "maxLength": 256 },
"type": {
"type": "string",
"enum": ["human", "agent", "service", "workflow"]
},
"displayName": { "type": "string", "minLength": 1, "maxLength": 256 }
}
},
"traceContext": {
"type": "object",
"additionalProperties": false,
"required": ["traceparent"],
"properties": {
"traceparent": {
"type": "string",
"pattern": "^[\\da-f]{2}-[\\da-f]{32}-[\\da-f]{16}-[\\da-f]{2}$"

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Reject non-compliant traceparent identifiers

For v1 records, this pattern accepts values such as ff-00000000000000000000000000000000-0000000000000000-00, because it only checks lowercase hex lengths. The W3C Trace Context spec forbids version ff and all-zero trace-id/parent-id, so a record can satisfy the v1 schema while compliant downstream tracers must ignore its traceparent.

Useful? React with 👍 / 👎.

},
"tracestate": { "type": "string", "maxLength": 512 }
}
},
"lifecycleMetadata": {
"type": "object",
"required": [
"correlationId",
"promptId",
"runId",
"repo",
"actor",
"timestamp",
"schemaVersion",
"traceContext"
],
"properties": {
"correlationId": { "type": "string", "minLength": 1, "maxLength": 128 },
"promptId": { "type": "string", "minLength": 1, "maxLength": 128 },
"runId": { "type": "string", "minLength": 1, "maxLength": 128 },
"repo": {
"type": "string",
"pattern": "^[A-Za-z0-9_.-]+/[A-Za-z0-9_.-]+$"
},
"actor": { "$ref": "#/$defs/actor" },
"timestamp": { "type": "string", "format": "date-time" },
"schemaVersion": { "const": "1.0.0" },
"traceContext": { "$ref": "#/$defs/traceContext" }
}
},
"evidence": {
"type": "object",
"additionalProperties": false,
"required": ["kind", "uri"],
"properties": {
"kind": { "type": "string", "minLength": 1, "maxLength": 64 },
"uri": { "type": "string", "format": "uri" },
"sha256": { "type": "string", "pattern": "^[\\da-f]{64}$" }
}
}
}
}
51 changes: 51 additions & 0 deletions schemas/v1.0/evaluation-result.schema.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,51 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://schemas.coding-autopilot.dev/v1.0/evaluation-result.schema.json",
"title": "EvaluationResult",
"type": "object",
"allOf": [
{
"$ref": "common.schema.json#/$defs/lifecycleMetadata"
},
{
"type": "object",
"required": [
"kind",
"evaluator",
"outcome",
"metrics",
"evidence"
],
"properties": {
"kind": {
"const": "EvaluationResult"
},
"evaluator": {
"type": "string",
"minLength": 1,
"maxLength": 256
},
"outcome": {
"enum": [
"passed",
"failed",
"inconclusive"
]
},
"metrics": {
"type": "object",
"minProperties": 1,
"additionalProperties": {
"type": "number"
}
},
"evidence": {
"type": "array",
"minItems": 1,
"items": { "$ref": "common.schema.json#/$defs/evidence" }
}
}
}
],
"unevaluatedProperties": false
}
47 changes: 47 additions & 0 deletions schemas/v1.0/policy-decision.schema.json
Original file line number Diff line number Diff line change
@@ -0,0 +1,47 @@
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://schemas.coding-autopilot.dev/v1.0/policy-decision.schema.json",
"title": "PolicyDecision",
"type": "object",
"allOf": [
{
"$ref": "common.schema.json#/$defs/lifecycleMetadata"
},
{
"type": "object",
"required": [
"kind",
"decision",
"policyVersion",
"reasons"
],
"properties": {
"kind": {
"const": "PolicyDecision"
},
"decision": {
"enum": [
"allow",
"deny",
"require-approval"
]
},
"policyVersion": {
"type": "string",
"minLength": 1,
"maxLength": 64
},
"reasons": {
"type": "array",
"minItems": 1,
"items": {
"type": "string",
"minLength": 1,
"maxLength": 1000
}
}
}
}
],
"unevaluatedProperties": false
}
Loading
Loading