{"openapi":"3.1.0","info":{"title":"ClearTrace AI Integration API","version":"1.0.0","description":"Assistant-safe API surface for project kits, scanner config, validation, and ingestion."},"servers":[{"url":"https://api.cleartrace.dev/ai-integration/v1"}],"externalDocs":{"description":"Swagger UI","url":"https://api.cleartrace.dev/ai-integration/v1/docs"},"tags":[{"name":"Public discovery","description":"Open guidance and schemas. These endpoints do not return tenant, solution, project, or customer evidence data."},{"name":"Authenticated workspace discovery","description":"Tenant and solution registry reads. Requires a scoped ClearTrace machine API key."},{"name":"Authenticated capabilities","description":"Read-only scoped-key capabilities and visible boundary diagnostics. Requires a valid ClearTrace machine API key."},{"name":"Project context","description":"Project kit, scanner, foundation, context, and change-state reads. Requires a scoped ClearTrace machine API key."},{"name":"Working plans","description":"Private or team-visible assistant working plans. Requires scoped ClearTrace machine API key permissions."},{"name":"Validation","description":"Payload validation only. These endpoints do not store data."},{"name":"Machine ingestion","description":"Write path for approved scanner or assistant pushes. Requires a scoped ClearTrace machine API key."}],"paths":{"/solutions/{solutionId}/release-policy":{"get":{"summary":"Read solution release version policy","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"solutionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Scoped release result. Writes record evidence only."},"400":{"description":"Invalid request or missing approval"},"403":{"description":"Scope/grant required"},"409":{"description":"Stale revision, plan or idempotency conflict"},"503":{"description":"Unavailable or bounded operation timed out; no partial result"}}},"put":{"summary":"Apply exact approved policy preview","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"solutionId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"policy":{"type":"object","additionalProperties":false,"properties":{"scheme":{"type":"string","enum":["semver","calendar"]},"initialVersion":{"type":"string","minLength":1,"maxLength":60}},"required":["scheme","initialVersion"]},"approved":{"const":true},"planHash":{"type":"string","pattern":"^sha256:[a-f0-9]{64}$"}},"required":["policy","approved","planHash"]}}}},"responses":{"200":{"description":"Scoped release result. Writes record evidence only."},"400":{"description":"Invalid request or missing approval"},"403":{"description":"Scope/grant required"},"409":{"description":"Stale revision, plan or idempotency conflict"},"503":{"description":"Unavailable or bounded operation timed out; no partial result"}}}},"/solutions/{solutionId}/release-policy/preview":{"post":{"summary":"Preview initial version policy without mutation","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"solutionId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"scheme":{"type":"string","enum":["semver","calendar"]},"initialVersion":{"type":"string","minLength":1,"maxLength":60}},"required":["scheme","initialVersion"]}}}},"responses":{"200":{"description":"Scoped release result. Writes record evidence only."},"400":{"description":"Invalid request or missing approval"},"403":{"description":"Scope/grant required"},"409":{"description":"Stale revision, plan or idempotency conflict"},"503":{"description":"Unavailable or bounded operation timed out; no partial result"}}}},"/solutions/{solutionId}/releases/preview":{"post":{"summary":"Preview next version without reserving it","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"solutionId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"idempotencyKey":{"type":"string","minLength":1,"maxLength":160},"title":{"type":"string","minLength":1,"maxLength":240},"environmentId":{"type":"string","minLength":1,"maxLength":160},"bump":{"type":"string","enum":["major","minor","patch"]},"recordingMode":{"type":"string","enum":["planned","already_deployed"],"default":"planned","description":"Use already_deployed only to record observed existing deployments; never redeploy or manufacture a binary digest for the ledger."}},"required":["idempotencyKey","title","environmentId"]}}}},"responses":{"200":{"description":"Scoped release result. Writes record evidence only."},"400":{"description":"Invalid request or missing approval"},"403":{"description":"Scope/grant required"},"409":{"description":"Stale revision, plan or idempotency conflict"},"503":{"description":"Unavailable or bounded operation timed out; no partial result"}}}},"/solutions/{solutionId}/releases/prepare":{"post":{"summary":"Reserve exact approved version idempotently; does not deploy","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"solutionId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"request":{"type":"object","additionalProperties":false,"properties":{"idempotencyKey":{"type":"string","minLength":1,"maxLength":160},"title":{"type":"string","minLength":1,"maxLength":240},"environmentId":{"type":"string","minLength":1,"maxLength":160},"bump":{"type":"string","enum":["major","minor","patch"]},"recordingMode":{"type":"string","enum":["planned","already_deployed"],"default":"planned","description":"Use already_deployed only to record observed existing deployments; never redeploy or manufacture a binary digest for the ledger."}},"required":["idempotencyKey","title","environmentId"]},"approved":{"const":true},"planHash":{"type":"string","pattern":"^sha256:[a-f0-9]{64}$"}},"required":["request","approved","planHash"]}}}},"responses":{"200":{"description":"Scoped release result. Writes record evidence only."},"400":{"description":"Invalid request or missing approval"},"403":{"description":"Scope/grant required"},"409":{"description":"Stale revision, plan or idempotency conflict"},"503":{"description":"Unavailable or bounded operation timed out; no partial result"}}}},"/solutions/{solutionId}/releases":{"get":{"summary":"Cursor-paged release summaries without history or diffs","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"solutionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":25}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Scoped release result. Writes record evidence only."},"400":{"description":"Invalid request or missing approval"},"403":{"description":"Scope/grant required"},"409":{"description":"Stale revision, plan or idempotency conflict"},"503":{"description":"Unavailable or bounded operation timed out; no partial result"}}}},"/solutions/{solutionId}/releases/{releaseId}":{"get":{"summary":"Read one release and frozen manifest","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"solutionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"releaseId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Scoped release result. Writes record evidence only."},"400":{"description":"Invalid request or missing approval"},"403":{"description":"Scope/grant required"},"409":{"description":"Stale revision, plan or idempotency conflict"},"503":{"description":"Unavailable or bounded operation timed out; no partial result"}}}},"/solutions/{solutionId}/releases/{releaseId}/contents":{"get":{"summary":"What the release shipped: per project, the commits of the change packages it cites, whether that range starts at the previous release, and the changes and tickets those commits belong to (cleartrace-release-contents-v1)","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"solutionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"releaseId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Scoped release result. Writes record evidence only."},"400":{"description":"Invalid request or missing approval"},"403":{"description":"Scope/grant required"},"409":{"description":"Stale revision, plan or idempotency conflict"},"503":{"description":"Unavailable or bounded operation timed out; no partial result"}}}},"/solutions/{solutionId}/releases/{releaseId}/deployments":{"get":{"summary":"Cursor-paged compact deployment attempts","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"solutionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"releaseId","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":25}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Scoped release result. Writes record evidence only."},"400":{"description":"Invalid request or missing approval"},"403":{"description":"Scope/grant required"},"409":{"description":"Stale revision, plan or idempotency conflict"},"503":{"description":"Unavailable or bounded operation timed out; no partial result"}}}},"/solutions/{solutionId}/releases/{releaseId}/events":{"get":{"summary":"Cursor-paged release/deployment history","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"solutionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"releaseId","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":25}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"description":"Scoped release result. Writes record evidence only."},"400":{"description":"Invalid request or missing approval"},"403":{"description":"Scope/grant required"},"409":{"description":"Stale revision, plan or idempotency conflict"},"503":{"description":"Unavailable or bounded operation timed out; no partial result"}}},"post":{"summary":"Append an approved revision-checked event; never execute a deployment","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"solutionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"releaseId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"event":{"oneOf":[{"type":"object","additionalProperties":false,"properties":{"eventId":{"type":"string","minLength":1,"maxLength":160},"expectedRevision":{"type":"integer","minimum":1},"type":{"const":"candidate_frozen"},"summary":{"type":"string","minLength":1,"maxLength":1000},"payload":{"type":"object","additionalProperties":false,"properties":{"manifest":{"type":"object","additionalProperties":false,"properties":{"components":{"type":"array","minItems":1,"maxItems":50,"items":{"oneOf":[{"type":"object","additionalProperties":false,"properties":{"projectId":{"type":"string","minLength":1,"maxLength":160},"commitSha":{"type":"string","pattern":"^[a-f0-9]{40}([a-f0-9]{24})?$"},"rangeException":{"type":"object","additionalProperties":false,"required":["reason"],"properties":{"reason":{"type":"string","minLength":10,"maxLength":500}},"description":"Only when the cited change package cannot start at the previous release's commit for this project (a rollback, rewritten history): say why."},"artifactDigest":{"type":"string","pattern":"^sha256:[a-f0-9]{64}$","description":"SHA-256 of the actual deployed artifact bytes, not the approval plan or a newly rebuilt/source archive."}},"required":["projectId","commitSha","artifactDigest"]},{"type":"object","additionalProperties":false,"properties":{"projectId":{"type":"string","minLength":1,"maxLength":160},"commitSha":{"type":"string","pattern":"^[a-f0-9]{40}([a-f0-9]{24})?$"},"rangeException":{"type":"object","additionalProperties":false,"required":["reason"],"properties":{"reason":{"type":"string","minLength":10,"maxLength":500}},"description":"Only when the cited change package cannot start at the previous release's commit for this project (a rollback, rewritten history): say why."},"artifactDigest":{"type":"null"},"artifactEvidence":{"type":"object","additionalProperties":false,"properties":{"status":{"const":"unavailable"},"reason":{"type":"string","minLength":1,"maxLength":500},"references":{"type":"array","maxItems":200,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"kind":{"type":"string","enum":["package","ticket_revision","change_capsule","evidence"]},"id":{"type":"string","minLength":1,"maxLength":500}},"required":["kind","id"]},"minItems":1}},"required":["status","reason","references"]}},"required":["projectId","commitSha","artifactDigest","artifactEvidence"]}]}},"references":{"type":"array","maxItems":200,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"kind":{"type":"string","enum":["package","ticket_revision","change_capsule","evidence"]},"id":{"type":"string","minLength":1,"maxLength":500}},"required":["kind","id"]}}},"required":["components","references"]}},"required":["manifest"]}},"required":["eventId","expectedRevision","type","summary","payload"]},{"type":"object","additionalProperties":false,"properties":{"eventId":{"type":"string","minLength":1,"maxLength":160},"expectedRevision":{"type":"integer","minimum":1},"type":{"const":"deployment_started"},"summary":{"type":"string","minLength":1,"maxLength":1000},"payload":{"type":"object","additionalProperties":false,"properties":{"deploymentId":{"type":"string","minLength":1,"maxLength":160},"environmentId":{"type":"string","minLength":1,"maxLength":160},"targets":{"type":"array","minItems":1,"maxItems":100,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":160}},"references":{"type":"array","maxItems":200,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"kind":{"type":"string","enum":["package","ticket_revision","change_capsule","evidence"]},"id":{"type":"string","minLength":1,"maxLength":500}},"required":["kind","id"]}},"observedAt":{"type":"string","format":"date-time","pattern":"^(?!0000-)\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$","description":"Actual deployment time in UTC (Z), not the time this ledger entry is recorded. Required in already_deployed mode."}},"required":["deploymentId","environmentId","targets","references"]}},"required":["eventId","expectedRevision","type","summary","payload"]},{"type":"object","additionalProperties":false,"properties":{"eventId":{"type":"string","minLength":1,"maxLength":160},"expectedRevision":{"type":"integer","minimum":1},"type":{"const":"deployment_finished"},"summary":{"type":"string","minLength":1,"maxLength":1000},"payload":{"oneOf":[{"type":"object","additionalProperties":false,"properties":{"deploymentId":{"type":"string","minLength":1,"maxLength":160},"outcome":{"const":"succeeded"},"references":{"type":"array","maxItems":200,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"kind":{"type":"string","enum":["package","ticket_revision","change_capsule","evidence"]},"id":{"type":"string","minLength":1,"maxLength":500}},"required":["kind","id"]}},"observedComponents":{"type":"array","minItems":1,"maxItems":50,"items":{"oneOf":[{"type":"object","additionalProperties":false,"properties":{"projectId":{"type":"string","minLength":1,"maxLength":160},"commitSha":{"type":"string","pattern":"^[a-f0-9]{40}([a-f0-9]{24})?$"},"rangeException":{"type":"object","additionalProperties":false,"required":["reason"],"properties":{"reason":{"type":"string","minLength":10,"maxLength":500}},"description":"Only when the cited change package cannot start at the previous release's commit for this project (a rollback, rewritten history): say why."},"artifactDigest":{"type":"string","pattern":"^sha256:[a-f0-9]{64}$","description":"SHA-256 of the actual deployed artifact bytes, not the approval plan or a newly rebuilt/source archive."}},"required":["projectId","commitSha","artifactDigest"]},{"type":"object","additionalProperties":false,"properties":{"projectId":{"type":"string","minLength":1,"maxLength":160},"commitSha":{"type":"string","pattern":"^[a-f0-9]{40}([a-f0-9]{24})?$"},"rangeException":{"type":"object","additionalProperties":false,"required":["reason"],"properties":{"reason":{"type":"string","minLength":10,"maxLength":500}},"description":"Only when the cited change package cannot start at the previous release's commit for this project (a rollback, rewritten history): say why."},"artifactDigest":{"type":"null"},"artifactEvidence":{"type":"object","additionalProperties":false,"properties":{"status":{"const":"unavailable"},"reason":{"type":"string","minLength":1,"maxLength":500},"references":{"type":"array","maxItems":200,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"kind":{"type":"string","enum":["package","ticket_revision","change_capsule","evidence"]},"id":{"type":"string","minLength":1,"maxLength":500}},"required":["kind","id"]},"minItems":1}},"required":["status","reason","references"]}},"required":["projectId","commitSha","artifactDigest","artifactEvidence"]}]}},"observedAt":{"type":"string","format":"date-time","pattern":"^(?!0000-)\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$","description":"Actual deployment time in UTC (Z), not the time this ledger entry is recorded. Required in already_deployed mode."},"deploymentEvidence":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","additionalProperties":false,"properties":{"projectId":{"type":"string","minLength":1,"maxLength":160},"workflowRunRef":{"type":"object","additionalProperties":false,"properties":{"kind":{"const":"evidence"},"id":{"type":"string","minLength":1,"maxLength":500}},"required":["kind","id"]},"liveBuildRef":{"type":"object","additionalProperties":false,"properties":{"kind":{"const":"evidence"},"id":{"type":"string","minLength":1,"maxLength":500}},"required":["kind","id"]},"liveBuildIdentity":{"type":"string","minLength":1,"maxLength":500}},"required":["projectId","workflowRunRef","liveBuildRef","liveBuildIdentity"]}}},"required":["deploymentId","outcome","references","observedComponents"]},{"type":"object","additionalProperties":false,"properties":{"deploymentId":{"type":"string","minLength":1,"maxLength":160},"outcome":{"type":"string","enum":["partial","failed","verification_pending"]},"references":{"type":"array","maxItems":200,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"kind":{"type":"string","enum":["package","ticket_revision","change_capsule","evidence"]},"id":{"type":"string","minLength":1,"maxLength":500}},"required":["kind","id"]}},"observedAt":{"type":"string","format":"date-time","pattern":"^(?!0000-)\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(?:\\.\\d{1,3})?Z$","description":"Actual deployment time in UTC (Z), not the time this ledger entry is recorded. Required in already_deployed mode."}},"required":["deploymentId","outcome","references"]}]}},"required":["eventId","expectedRevision","type","summary","payload"]},{"type":"object","additionalProperties":false,"properties":{"eventId":{"type":"string","minLength":1,"maxLength":160},"expectedRevision":{"type":"integer","minimum":1},"type":{"const":"note"},"summary":{"type":"string","minLength":1,"maxLength":1000},"payload":{"type":"object","additionalProperties":false,"properties":{"references":{"type":"array","maxItems":200,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"kind":{"type":"string","enum":["package","ticket_revision","change_capsule","evidence"]},"id":{"type":"string","minLength":1,"maxLength":500}},"required":["kind","id"]}}},"required":["references"]}},"required":["eventId","expectedRevision","type","summary","payload"]},{"type":"object","additionalProperties":false,"properties":{"eventId":{"type":"string","minLength":1,"maxLength":160},"expectedRevision":{"type":"integer","minimum":1},"type":{"const":"release_completed"},"summary":{"type":"string","minLength":1,"maxLength":1000},"payload":{"type":"object","additionalProperties":false,"properties":{"references":{"type":"array","maxItems":200,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"kind":{"type":"string","enum":["package","ticket_revision","change_capsule","evidence"]},"id":{"type":"string","minLength":1,"maxLength":500}},"required":["kind","id"]}}},"required":["references"]}},"required":["eventId","expectedRevision","type","summary","payload"]},{"type":"object","additionalProperties":false,"properties":{"eventId":{"type":"string","minLength":1,"maxLength":160},"expectedRevision":{"type":"integer","minimum":1},"type":{"const":"cancelled"},"summary":{"type":"string","minLength":1,"maxLength":1000},"payload":{"type":"object","additionalProperties":false,"properties":{"references":{"type":"array","maxItems":200,"uniqueItems":true,"items":{"type":"object","additionalProperties":false,"properties":{"kind":{"type":"string","enum":["package","ticket_revision","change_capsule","evidence"]},"id":{"type":"string","minLength":1,"maxLength":500}},"required":["kind","id"]}}},"required":["references"]}},"required":["eventId","expectedRevision","type","summary","payload"]}]},"approved":{"const":true}},"required":["event","approved"]}}}},"responses":{"200":{"description":"Scoped release result. Writes record evidence only."},"400":{"description":"Invalid request or missing approval"},"403":{"description":"Scope/grant required"},"409":{"description":"Stale revision, plan or idempotency conflict"},"503":{"description":"Unavailable or bounded operation timed out; no partial result"}}}},"/solutions/{solutionId}/environments/preview":{"post":{"summary":"Preview environment metadata registration without writing","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"solutionId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["idempotencyKey","name","environmentType"],"properties":{"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$","maxLength":80},"name":{"type":"string","pattern":"^[A-Za-z0-9](?:[A-Za-z0-9 ._-]{0,78}[A-Za-z0-9._-])?$","maxLength":80,"description":"Trimmed ASCII display name; case-insensitive uniqueness within the solution."},"environmentType":{"type":"string","enum":["development","test","staging","production","other"]}}}}}},"responses":{"200":{"description":"Canonical environment summary, action and exact planHash; metadata only."},"400":{"description":"Invalid input or missing approval"},"403":{"description":"manage:solutions and matching solution/workspace grant required"},"404":{"description":"Solution not found"},"409":{"description":"Stale plan, name/identity/idempotency conflict"},"413":{"description":"8 KiB request budget exceeded"},"503":{"description":"Unavailable, busy, timeout or budget failure; no partial result"}}}},"/solutions/{solutionId}/environments/register":{"post":{"summary":"Register exact approved metadata plan idempotently; does not deploy","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"solutionId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["request","planHash","approved"],"properties":{"request":{"type":"object","additionalProperties":false,"required":["idempotencyKey","name","environmentType"],"properties":{"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$","maxLength":80},"name":{"type":"string","pattern":"^[A-Za-z0-9](?:[A-Za-z0-9 ._-]{0,78}[A-Za-z0-9._-])?$","maxLength":80,"description":"Trimmed ASCII display name; case-insensitive uniqueness within the solution."},"environmentType":{"type":"string","enum":["development","test","staging","production","other"]}}},"planHash":{"type":"string","pattern":"^sha256:[a-f0-9]{64}$"},"approved":{"const":true}}}}}},"responses":{"200":{"description":"Canonical environment summary, action and exact planHash; metadata only."},"400":{"description":"Invalid input or missing approval"},"403":{"description":"manage:solutions and matching solution/workspace grant required"},"404":{"description":"Solution not found"},"409":{"description":"Stale plan, name/identity/idempotency conflict"},"413":{"description":"8 KiB request budget exceeded"},"503":{"description":"Unavailable, busy, timeout or budget failure; no partial result"}}}},"/solutions/{solutionId}/evidence/preview":{"post":{"summary":"Preview canonical evidence registration from accepted test runs; no writes","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"solutionId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["idempotencyKey","items"],"properties":{"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$","maxLength":80},"items":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","additionalProperties":false,"required":["testRunId","evidenceType"],"properties":{"testRunId":{"type":"string","minLength":1,"maxLength":500},"evidenceType":{"type":"string","enum":["workflow_run","live_build","deployment_verification"]},"uri":{"type":"string","format":"uri","pattern":"^https://","maxLength":1000,"description":"Public provenance URL; no credentials, query strings or fragments. Not fetched by ClearTrace."},"commitSha":{"type":"string","pattern":"^[a-f0-9]{40}([a-f0-9]{24})?$"},"buildIdentity":{"type":"string","minLength":1,"maxLength":500}}}}}}}}},"responses":{"200":{"description":"Canonical immutable evidence metadata; publisher-reported, not independent verification"},"400":{"description":"Invalid request or approval"},"401":{"description":"Authentication required"},"403":{"description":"Matching solution/workspace grant and read:working_plan or write:working_plan required"},"404":{"description":"Solution/evidence not found"},"409":{"description":"Missing source, stale plan, changed stored metadata or idempotency conflict"},"413":{"description":"32 KiB request budget exceeded"},"503":{"description":"Unavailable/busy/timeout/budget failure; no partial result"}}}},"/solutions/{solutionId}/evidence/register":{"post":{"summary":"Atomically register the exact approved immutable evidence snapshot","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"solutionId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["request","planHash","approved"],"properties":{"request":{"type":"object","additionalProperties":false,"required":["idempotencyKey","items"],"properties":{"idempotencyKey":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,79}$","maxLength":80},"items":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","additionalProperties":false,"required":["testRunId","evidenceType"],"properties":{"testRunId":{"type":"string","minLength":1,"maxLength":500},"evidenceType":{"type":"string","enum":["workflow_run","live_build","deployment_verification"]},"uri":{"type":"string","format":"uri","pattern":"^https://","maxLength":1000,"description":"Public provenance URL; no credentials, query strings or fragments. Not fetched by ClearTrace."},"commitSha":{"type":"string","pattern":"^[a-f0-9]{40}([a-f0-9]{24})?$"},"buildIdentity":{"type":"string","minLength":1,"maxLength":500}}}}}},"planHash":{"type":"string","pattern":"^sha256:[a-f0-9]{64}$"},"approved":{"const":true}}}}}},"responses":{"200":{"description":"Canonical immutable evidence metadata; publisher-reported, not independent verification"},"400":{"description":"Invalid request or approval"},"401":{"description":"Authentication required"},"403":{"description":"Matching solution/workspace grant and read:working_plan or write:working_plan required"},"404":{"description":"Solution/evidence not found"},"409":{"description":"Missing source, stale plan, changed stored metadata or idempotency conflict"},"413":{"description":"32 KiB request budget exceeded"},"503":{"description":"Unavailable/busy/timeout/budget failure; no partial result"}}}},"/solutions/{solutionId}/evidence/{evidenceId}":{"get":{"summary":"Read one registered evidence record, not a graph","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"solutionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"evidenceId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Canonical immutable evidence metadata; publisher-reported, not independent verification"},"400":{"description":"Invalid request or approval"},"401":{"description":"Authentication required"},"403":{"description":"Matching solution/workspace grant and read:working_plan or write:working_plan required"},"404":{"description":"Solution/evidence not found"},"409":{"description":"Missing source, stale plan, changed stored metadata or idempotency conflict"},"413":{"description":"32 KiB request budget exceeded"},"503":{"description":"Unavailable/busy/timeout/budget failure; no partial result"}}}},"/openapi.json":{"get":{"tags":["Public discovery"],"summary":"Get this OpenAPI document","responses":{"200":{"description":"OpenAPI document"}}}},"/assistant-guide":{"get":{"tags":["Public discovery"],"summary":"Get assistant-safe integration procedure","responses":{"200":{"description":"Assistant guide"}}}},"/agent-spec":{"get":{"tags":["Public discovery"],"summary":"Get the generic ClearTrace assistant agent spec","responses":{"200":{"description":"Agent spec"}}}},"/developer-guide":{"get":{"tags":["Public discovery"],"summary":"Get human developer integration guidance","responses":{"200":{"description":"Developer guide"}}}},"/app-foundation":{"get":{"tags":["Public discovery"],"summary":"Get public app-foundation pointers","responses":{"200":{"description":"App foundation pointers"}}}},"/kit/releases":{"get":{"tags":["Public discovery"],"summary":"List immutable project-kit releases and compatibility policy","responses":{"200":{"description":"Project-kit release registry","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectKitReleaseRegistryResponse"}}}}}}},"/cli/releases/latest":{"get":{"tags":["Public discovery"],"summary":"Get the pinned ClearTrace CLI distribution manifest and commands","responses":{"200":{"description":"CLI distribution manifest"},"503":{"description":"CLI artifact unavailable in this API release"}}}},"/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz":{"get":{"tags":["Public discovery"],"summary":"Download the immutable ClearTrace CLI npm package","responses":{"200":{"description":"CLI npm tarball"},"503":{"description":"CLI artifact unavailable in this API release"}}}},"/kit/latest":{"get":{"tags":["Public discovery"],"summary":"Get the current published project-kit release","responses":{"200":{"description":"Current project-kit release manifest","content":{"application/json":{"schema":{"type":"object"}}}}}}},"/schemas/{schemaName}":{"get":{"tags":["Public discovery"],"summary":"Get a public JSON schema","parameters":[{"name":"schemaName","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"JSON schema"},"404":{"description":"Schema not found"}}}},"/intake/links":{"get":{"tags":["Intake"],"summary":"List intake links this key can see","description":"Each link belongs to a solution or one project, with its status and how many items are new. Use a linkId to filter items or submit one.","security":[{"scopedMachineApiKey":[]}],"responses":{"200":{"description":"Links"},"401":{"description":"ClearTrace API key required"}}}},"/intake/items":{"get":{"tags":["Intake"],"summary":"List intake items (new by default)","description":"Query: status (new, retired, closed, cancelled, converted or all), linkId, limit (1-100), offset. counts gives totals per status. Follow the triageIntake playbook.","security":[{"scopedMachineApiKey":[]}],"responses":{"200":{"description":"A page of items"},"401":{"description":"ClearTrace API key required"}}},"post":{"tags":["Intake"],"summary":"Submit an intake item (agent)","description":"Body: {linkId, kind (bug, question, feature, other), title, body, context (up to 20 text fields)}. Needs push:ticket; counts toward the monthly intake allowance (429 intake_monthly_limit_reached).","security":[{"scopedMachineApiKey":[]}],"responses":{"201":{"description":"The item"},"400":{"description":"Invalid item or linkId"},"429":{"description":"Monthly allowance reached"}}}},"/intake/items/{itemId}":{"get":{"tags":["Intake"],"summary":"Read an intake item and its status changes","security":[{"scopedMachineApiKey":[]}],"responses":{"200":{"description":"Item and events"},"404":{"description":"Not found or not visible"}}}},"/intake/items/{itemId}/decision":{"post":{"tags":["Intake"],"summary":"Record the user's decision on a new item","description":"Body: {decision: converted|retired|closed|cancelled, ticketId (when converted; its sourceRefs must include intake:<itemId>), note, decidedBy (the person)}. Final; needs push:ticket.","security":[{"scopedMachineApiKey":[]}],"responses":{"200":{"description":"The decided item"},"409":{"description":"Already decided, or the ticket lacks the intake ref"}}}},"/capabilities":{"get":{"tags":["Authenticated capabilities"],"summary":"Get scoped-key capabilities and visible boundary diagnostics","description":"Returns non-secret key status, scopes, visible solution/project counts, allowed push types, and recommended next reads. Use this before choosing MCP/API actions.","security":[{"scopedMachineApiKey":[]}],"responses":{"200":{"description":"Capability summary","content":{"application/json":{"schema":{"$ref":"#/components/schemas/IntegrationCapabilities"}}}},"401":{"description":"ClearTrace API key required"}}}},"/search":{"post":{"tags":["Authenticated work retrieval"],"summary":"Search tickets and change capsules with deterministic or hybrid retrieval","description":"Permission-safe deterministic retrieval is always available. Auto and hybrid modes add configured semantic similarity without loading the full ledger into an AI prompt, and return an explicit fallback when semantic retrieval is unavailable.","security":[{"scopedMachineApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentSearchRequest"}}}},"responses":{"200":{"description":"Ranked deterministic or hybrid search results"},"400":{"description":"Invalid search request or cursor"},"401":{"description":"ClearTrace API key required"},"403":{"description":"Required read scope missing"}}}},"/workspace-discovery/preview":{"post":{"tags":["Authenticated workspace discovery"],"summary":"Preview metadata-only solution and project adoption","description":"Builds a deterministic create/reuse/update plan with field-level metadata changes without changing the ClearTrace catalog. Raw source, local paths, and credentials are rejected.","security":[{"scopedMachineApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceDiscoveryRequest"}}}},"responses":{"200":{"description":"Deterministic discovery plan with per-operation authorization"},"400":{"description":"Invalid or unsafe discovery metadata"},"401":{"description":"ClearTrace API key required"},"403":{"description":"read:registry scope required"}}}},"/workspace-discovery/apply":{"post":{"tags":["Authenticated workspace discovery"],"summary":"Apply an explicitly approved current discovery plan","description":"Recomputes the plan, rejects stale plan hashes, validates operation dependencies and key grants, and creates only selected solution/project records.","security":[{"scopedMachineApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkspaceDiscoveryApplyRequest"}}}},"responses":{"200":{"description":"Existing registry objects reused"},"201":{"description":"Approved registry objects created"},"400":{"description":"Approval, selection, or dependency invalid"},"401":{"description":"ClearTrace API key required"},"403":{"description":"Owned key, manage scope, or catalog grant required"},"409":{"description":"Plan stale or discovery conflict"}}}},"/solutions":{"get":{"tags":["Authenticated workspace discovery"],"summary":"List solutions available to the authenticated context","security":[{"scopedMachineApiKey":[]}],"responses":{"200":{"description":"Solution summaries"},"401":{"description":"ClearTrace API key required"},"403":{"description":"API key scope required"}}}},"/solutions/{solutionId}/projects":{"get":{"tags":["Authenticated workspace discovery"],"summary":"List projects for a solution","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"solutionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Project summaries"},"401":{"description":"ClearTrace API key required"},"403":{"description":"API key scope required"},"404":{"description":"Solution not found"}}}},"/solutions/{solutionId}/environments":{"get":{"tags":["Authenticated workspace discovery"],"summary":"List one bounded page of registered environment IDs, names and types","description":"Requires read:registry or read:working_plan and a matching solution/workspace grant. Follow page.nextCursor; prod is not an automatic alias. Reads no graph, source, credentials or architecture history.","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"solutionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":50,"default":25}},{"name":"cursor","in":"query","schema":{"type":"string","maxLength":512}}],"responses":{"200":{"description":"Environment summaries with page.limit, page.hasMore and page.nextCursor","content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["data","page"],"properties":{"data":{"type":"array","maxItems":50,"items":{"type":"object","additionalProperties":false,"required":["environmentId","solutionId","name","environmentType"],"properties":{"environmentId":{"type":"string"},"solutionId":{"type":"string"},"name":{"type":"string"},"environmentType":{"type":"string"}}}},"page":{"type":"object","additionalProperties":false,"required":["limit","hasMore","nextCursor"],"properties":{"limit":{"type":"integer","minimum":1,"maximum":50},"hasMore":{"type":"boolean"},"nextCursor":{"type":["string","null"]}}}}}}}},"400":{"description":"Invalid query or scope-bound cursor"},"401":{"description":"Machine API key required"},"403":{"description":"Scope or grant required"},"404":{"description":"Solution not found"},"503":{"description":"Explicit read budget or timeout failure; no partial result"}}}},"/solutions/{solutionId}/operation-runs":{"get":{"tags":["Authenticated workspace discovery"],"summary":"List operation runs recorded at task closeout, newest first","description":"Who ran which deploy, migration, clone, rotation, backup or restore against which environment, and when. Requires read:project_kit; a project-scoped key sees only its projects' runs. Paged by limit and offset; follow nextOffset until hasMore=false.","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"solutionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"environment","in":"query","schema":{"type":"string","maxLength":200}},{"name":"service","in":"query","schema":{"type":"string","maxLength":200}},{"name":"operation","in":"query","schema":{"type":"string","maxLength":200}},{"name":"projectId","in":"query","schema":{"type":"string","maxLength":200}},{"name":"kind","in":"query","schema":{"type":"string","enum":["provision","deploy","migrate","rotate","backup","restore","clone","seed","check","other"]}},{"name":"outcome","in":"query","schema":{"type":"string","enum":["succeeded","failed","partial","cancelled"]}},{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","schema":{"type":"integer","minimum":0,"maximum":10000,"default":0}}],"responses":{"200":{"description":"data {items[], total, limit, offset, hasMore, nextOffset}"},"400":{"description":"Invalid query"},"401":{"description":"Machine API key required"},"403":{"description":"Scope or grant required"},"404":{"description":"Solution not found"},"503":{"description":"Operation runs unavailable, read timeout or budget"}}},"post":{"tags":["Authenticated workspace discovery"],"summary":"Record operation runs without a new code change, after approving the preview's planHash","description":"Body {approved: true, planHash, request: {projectId, operationRuns}} with the request exactly as previewed. For a deploy of commits already recorded, a backup or a rotation; runs that come with a change go in its task closeout. Requires push:package for the project. An identical retry answers already_applied. CLI: cleartrace operation-run submit.","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"solutionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"data {status: already_applied, ...}"},"201":{"description":"data {status: applied, planHash, runs[{runIndex, runId, status}]}"},"400":{"description":"Approval missing or invalid runs"},"403":{"description":"push:package for the project required"},"404":{"description":"Project not found in this solution"},"409":{"description":"planHash does not match the request (operation_run_plan_stale)"},"503":{"description":"Operation runs unavailable"}}}},"/solutions/{solutionId}/operation-runs/preview":{"post":{"tags":["Authenticated workspace discovery"],"summary":"Preview operation runs without a new code change","description":"Body {projectId, operationRuns: [run, ...]}; returns planHash, canSubmit, runs [{runIndex, runId, ...}] and diagnostics. Nothing is written. Requires push:package for the project. CLI: cleartrace operation-run preview.","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"solutionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"data {contractId: cleartrace-operation-run-plan-v1, solutionId, projectId, planHash, canSubmit, runs[], diagnostics[]}"},"400":{"description":"Unknown field"},"403":{"description":"push:package for the project required"},"404":{"description":"Project not found in this solution"}}}},"/solutions/{solutionId}/operations/summary":{"get":{"tags":["Authenticated workspace discovery"],"summary":"Last run and 30-day counts per environment and operation","description":"One group per environment and declared operation name (runs without a name group by kind): lastRun {runId, outcome, startedAt, finishedAt, ranBy, actor, target} and counts for the last 30 days. Same scope and boundary as operation-runs.","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"solutionId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"data {solutionId, asOf, windowDays, groups[], truncated}"},"401":{"description":"Machine API key required"},"403":{"description":"Scope or grant required"},"404":{"description":"Solution not found"},"503":{"description":"Operation runs unavailable or read timeout"}}}},"/solutions/{solutionId}/architecture":{"get":{"tags":["Authenticated workspace discovery"],"summary":"Get current solution architecture and immutable history","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"solutionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"domain","in":"query","required":false,"schema":{"type":"string","enum":["system_architecture","cloud_and_deployment","data_model","data_flow"]}},{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["infrastructure","data_model","data_flow"]}},{"name":"basis","in":"query","required":false,"schema":{"type":"string","enum":["declared","observed_runtime","inferred"]}},{"name":"environmentId","in":"query","required":false,"schema":{"type":"string"}},{"name":"includeHistory","in":"query","required":false,"schema":{"type":"string","enum":["true","false"]}},{"name":"objectOffset","in":"query","required":false,"schema":{"type":"integer","minimum":0}},{"name":"relationshipOffset","in":"query","required":false,"schema":{"type":"integer","minimum":0}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":10000}}],"description":"Current is composed server-side (nearest version of each key on each active baseline chain). When the composed view exceeds the read budget, or objectOffset/relationshipOffset/limit is supplied, current.page (cleartrace-architecture-current-page-v1) gives totals, counts by type, offsets and nextQuery, and data.truncated=true whenever objects or relationships were omitted; follow nextQuery until it is null. A truncated page is not the complete inventory and relationship resolution is not evaluated on it. data.historyTruncated=true means the oldest history entries were dropped to fit the response. domain=data_flow adds flows (cleartrace-flows-read-v1): flows[] with steps [{id, name, kind, service, database, table, basis, serviceObjectKey}], edges [{from, to, label}], documents [{path, objectKey, title, kind, status}], historyInfo and lastChange; document counts by kind and status; declarationGaps. List reads carry history counts, not events.","responses":{"200":{"description":"Current composed state (complete or an explicit page) and snapshot history"},"400":{"description":"Invalid state or page query"},"401":{"description":"ClearTrace API key required"},"403":{"description":"Workspace or solution grant required"},"404":{"description":"Solution not found"},"503":{"description":"A single record exceeds the read budget, or timeout; no partial result"}}}},"/solutions/{solutionId}/architecture/reconciliation/preview":{"post":{"tags":["Authenticated workspace discovery"],"summary":"Preview explicit system relationship retirements","description":"Requires manage:solutions and a matching solution or workspace grant. Server binds tenant/solution; request contains environmentId (explicit null if unrecorded), sourceScopeKey, baselineSnapshotId, and retirements. Each retirement needs a relationshipKey, nullable replacementRelationshipKey, reason and snapshot:<id> evidenceRefs. Replacement must already resolve in the declaring scope. Submit requires literal approved=true and the exact preview planHash. Partial history is preserved; hosted readback remains required. PostgreSQL transactional storage is required for submission.","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"solutionId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["request"],"properties":{"request":{"type":"object","additionalProperties":false,"required":["environmentId","sourceScopeKey","baselineSnapshotId","retirements"],"properties":{"environmentId":{"anyOf":[{"type":"null"},{"type":"string","minLength":1,"maxLength":160}]},"sourceScopeKey":{"type":"string","minLength":1,"maxLength":1024},"baselineSnapshotId":{"type":"string","minLength":1,"maxLength":1024},"retirements":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","additionalProperties":false,"required":["relationshipKey","replacementRelationshipKey","reason","evidenceRefs"],"properties":{"relationshipKey":{"type":"string","minLength":1,"maxLength":2048},"replacementRelationshipKey":{"anyOf":[{"type":"null"},{"type":"string","minLength":1,"maxLength":2048}]},"reason":{"type":"string","minLength":1,"maxLength":4000},"evidenceRefs":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","minLength":1,"maxLength":2048}}}}}}},"approved":{"type":"boolean","const":true},"planHash":{"type":"string","pattern":"^sha256:[a-f0-9]{64}$"}}}}}},"responses":{"200":{"description":"Preview or applied/already_applied receipt"},"400":{"description":"Invalid request or approval"},"401":{"description":"API key required"},"403":{"description":"Management scope and solution/workspace grant required"},"404":{"description":"Solution not found"},"409":{"description":"Stale baseline or approval conflict; preview again"},"503":{"description":"Transactional storage unavailable"}}}},"/solutions/{solutionId}/architecture/reconciliation/submit":{"post":{"tags":["Authenticated workspace discovery"],"summary":"Apply approved explicit system relationship retirements","description":"Requires manage:solutions and a matching solution or workspace grant. Server binds tenant/solution; request contains environmentId (explicit null if unrecorded), sourceScopeKey, baselineSnapshotId, and retirements. Each retirement needs a relationshipKey, nullable replacementRelationshipKey, reason and snapshot:<id> evidenceRefs. Replacement must already resolve in the declaring scope. Submit requires literal approved=true and the exact preview planHash. Partial history is preserved; hosted readback remains required. PostgreSQL transactional storage is required for submission.","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"solutionId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"required":["request","approved","planHash"],"properties":{"request":{"type":"object","additionalProperties":false,"required":["environmentId","sourceScopeKey","baselineSnapshotId","retirements"],"properties":{"environmentId":{"anyOf":[{"type":"null"},{"type":"string","minLength":1,"maxLength":160}]},"sourceScopeKey":{"type":"string","minLength":1,"maxLength":1024},"baselineSnapshotId":{"type":"string","minLength":1,"maxLength":1024},"retirements":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","additionalProperties":false,"required":["relationshipKey","replacementRelationshipKey","reason","evidenceRefs"],"properties":{"relationshipKey":{"type":"string","minLength":1,"maxLength":2048},"replacementRelationshipKey":{"anyOf":[{"type":"null"},{"type":"string","minLength":1,"maxLength":2048}]},"reason":{"type":"string","minLength":1,"maxLength":4000},"evidenceRefs":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","minLength":1,"maxLength":2048}}}}}}},"approved":{"type":"boolean","const":true},"planHash":{"type":"string","pattern":"^sha256:[a-f0-9]{64}$"}}}}}},"responses":{"200":{"description":"Preview or applied/already_applied receipt"},"400":{"description":"Invalid request or approval"},"401":{"description":"API key required"},"403":{"description":"Management scope and solution/workspace grant required"},"404":{"description":"Solution not found"},"409":{"description":"Stale baseline or approval conflict; preview again"},"503":{"description":"Transactional storage unavailable"}}}},"/solutions/{solutionId}/architecture/data-model/tables/{objectKey}":{"get":{"tags":["Authenticated workspace discovery"],"summary":"Get one data-model table: columns, relationships and history","description":"objectKey is a table key from current.objects of the data_model architecture read (URL-encoded). Returns cleartrace-data-model-table-v1: database {key, project, engine, name, sourceOfTruth, basis}, columns {name, type, nullable, default, key[], lastChange}, relationships {outgoing, incoming}, history {available, eventCount, truncated, order: newest_first, events[]} and drift. Each event has kind, summary, file, lines {start, end}, commit {sha, committedAt}, repository {repositoryId, url}, githubUrl (file at that commit and lines, github.com remotes only), change {changeCapsuleId, title} matched through the capsule's commits, tickets citing that change, and script: the statement text when the snapshot stored it, otherwise null with scriptSource github_link. Snapshots from CLIs before 0.1.79 have no history (history.available false, reason snapshot_predates_history).","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"solutionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"objectKey","in":"path","required":true,"schema":{"type":"string"}},{"name":"environmentId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The table"},"401":{"description":"ClearTrace API key required"},"403":{"description":"Workspace or solution grant required"},"404":{"description":"Solution or current table not found; currentObjectKey names the key that replaced an older one"}}}},"/solutions/{solutionId}/architecture/cloud-and-deployment/services/{service}":{"get":{"tags":["Authenticated workspace discovery"],"summary":"Get one cloud service: where it runs, what is deployed there, its operations and history","description":"service is a service name (or objectKey) from cloud.environments[].services[] of the cloud_and_deployment architecture read. Returns cleartrace-cloud-service-v1: kind, builtBy, basis (declared or assumed), environments [{name, provider, account, region, resource, url, catalogEnvironment, deployedRelease}], operations targeting it (lastRun null until operation runs are recorded), databases, observed workflow, IaC and script details, and history {available, eventCount, truncated, order: newest_first, events[]}. Each event has kind (added_file, changed_file, deleted_file), summary, source (workflow, iac, script, declaration, runbook), file, lines {start, end}, commit {sha, committedAt}, repository, githubUrl, change, tickets, and script (the hunk when the snapshot stored it, otherwise null with scriptSource github_link). Snapshots from CLIs before 0.1.80 read as one assumed environment, default, without history.","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"solutionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"service","in":"path","required":true,"schema":{"type":"string"}},{"name":"environmentId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The service"},"401":{"description":"ClearTrace API key required"},"403":{"description":"Workspace or solution grant required"},"404":{"description":"Solution or current service not found"}}}},"/solutions/{solutionId}/architecture/cloud-and-deployment/operations/{operation}":{"get":{"tags":["Authenticated workspace discovery"],"summary":"Get one operation: what it runs, its targets and history","description":"operation is an operation name (or objectKey) from cloud.operations[]. Returns cleartrace-cloud-operation-v1: kind, runs, runsInRepository, targets [{key, environment, service, database, resolved}], changes, approval, basis, lastRun (null until operation runs are recorded) and history, the same shape as a service's.","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"solutionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"operation","in":"path","required":true,"schema":{"type":"string"}},{"name":"environmentId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The operation"},"401":{"description":"ClearTrace API key required"},"403":{"description":"Workspace or solution grant required"},"404":{"description":"Solution or current operation not found"}}}},"/solutions/{solutionId}/architecture/data-flow/flows/{flow}":{"get":{"tags":["Authenticated workspace discovery"],"summary":"Get one flow: its steps across services and databases, its documents and history","description":"flow is a flow id (or objectKey) from flows.flows[] of the data_flow architecture read. Returns cleartrace-flow-v1: name, basis (declared or assumed), source {kind declaration|file|document, path, contractId}, steps [{id, name, kind source|process|store|review|output|external, service, database, table, basis, describedBy, serviceObjectKey}], edges, documents [{path, title, kind, status, fileUrl, ...}], relationships, and history {available, eventCount, truncated, order: newest_first, events[]} in the same shape as a service's: file, lines, commit, repository, githubUrl, change, tickets, and the flow file's diff when the snapshot stored it. A document's text is never stored. Snapshots from CLIs before 0.1.82 read each flow file's nodes as assumed steps, without history.","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"solutionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"flow","in":"path","required":true,"schema":{"type":"string"}},{"name":"environmentId","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"The flow"},"401":{"description":"ClearTrace API key required"},"403":{"description":"Workspace or solution grant required"},"404":{"description":"Solution or current flow not found"}}}},"/solutions/{solutionId}/documents":{"get":{"tags":["Authenticated workspace discovery"],"summary":"List the solution's documents: plans, designs, runbooks, decisions, current state, data flows, specs and notes","description":"From the current data_flow scans. Returns cleartrace-documents-read-v1, paged (limit 1..200, default 50; offset): items [{objectKey, path, title, kind, status, statusLabel, about, environments, updatedAt, basis (declared from the cleartrace header or assumed from the file name and Status line), header {present, valid}, supersededBy, supersedes, project, repository, fileUrl (GitHub at the scanned commit), lastCommit}], active first and superseded last; total, hasMore, nextOffset and counts by kind, status and basis. Filters: kind, status (draft, active, done, superseded, unknown), about (service:api, flow:<id>, database:<name>, project:<id>, operation:<name>), environment, project.","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"solutionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"kind","in":"query","required":false,"schema":{"type":"string","enum":["plan","design","runbook","decision","current_state","data_flow","spec","note"]}},{"name":"status","in":"query","required":false,"schema":{"type":"string","enum":["draft","active","done","superseded","unknown"]}},{"name":"about","in":"query","required":false,"schema":{"type":"string"}},{"name":"environment","in":"query","required":false,"schema":{"type":"string"}},{"name":"project","in":"query","required":false,"schema":{"type":"string"}},{"name":"environmentId","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":200}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0}}],"responses":{"200":{"description":"A page of documents"},"400":{"description":"Invalid filter"},"401":{"description":"ClearTrace API key required"},"403":{"description":"Workspace or solution grant required"},"404":{"description":"Solution not found"}}}},"/solutions/{solutionId}/architecture/scan-deficits":{"get":{"tags":["Authenticated workspace discovery"],"summary":"Get targeted architecture scan deficits","description":"Compares the currently materialized architecture with known scan-capable project scopes and returns only missing, partial, or below-policy domains. The response preserves untouched domains and source scopes, provides read-only CLI preview arguments, and includes orchestration-aware remediation runs with a short and detailed prompt.","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"solutionId","in":"path","required":true,"schema":{"type":"string"}},{"name":"domain","in":"query","required":false,"schema":{"type":"string","enum":["system_architecture","cloud_and_deployment","data_model","data_flow"]}}],"responses":{"200":{"description":"Deficit-aware scan recommendations"},"400":{"description":"Invalid architecture domain"},"401":{"description":"ClearTrace API key required"},"403":{"description":"Workspace or solution grant required"},"404":{"description":"Solution not found"}}}},"/components":{"get":{"tags":["Authenticated workspace discovery"],"summary":"List component manifests available to the authenticated context","security":[{"scopedMachineApiKey":[]}],"responses":{"200":{"description":"Component summaries"},"401":{"description":"ClearTrace API key required"},"403":{"description":"API key scope required"}}}},"/tickets":{"get":{"tags":["Work ledger"],"summary":"List tickets visible to the scoped API key","description":"Returns ticket state for the visible workspace, solution, or project scope. Project-scoped keys receive only tickets with an explicit reference to their granted project; unscoped solution tickets require solution- or workspace-level access.","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"solutionId","in":"query","required":false,"schema":{"type":"string"}},{"name":"projectId","in":"query","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string"}},{"name":"statusFamily","in":"query","required":false,"schema":{"type":"string","enum":["active","open","in_progress","blocked","resolved","closed"]},"description":"Stable lifecycle projection; active groups open, in-progress, and blocked work. The original producer state is returned as workflowState."},{"in":"query","name":"relationship","description":"Keep all visible tickets or narrow the list to tickets assigned to, reported by, or followed by the API-key owner.","schema":{"type":"string","enum":["all","assigned_to_me","reported_by_me","following","my_work"]}},{"name":"reportedByUserId","in":"query","required":false,"schema":{"type":"string"}},{"name":"assignedToUserId","in":"query","required":false,"schema":{"type":"string"}},{"name":"followedByUserId","in":"query","required":false,"schema":{"type":"string"}},{"name":"involvedUserId","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ticket summaries"},"400":{"description":"Scope mismatch"},"401":{"description":"ClearTrace API key required"},"403":{"description":"API key scope required"},"404":{"description":"Scope object not found"}}}},"/tickets/{ticketId}":{"get":{"tags":["Work ledger"],"summary":"Get a ticket visible to the scoped API key","description":"Legacy current projection plus all visible revisions within a 4 MiB read budget. Oversized histories fail explicitly. Prefer /record plus paged /history; this legacy contract is not silently truncated.","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"ticketId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Ticket detail"},"401":{"description":"ClearTrace API key required"},"403":{"description":"API key scope required"},"404":{"description":"Ticket not found"}}}},"/tickets/{ticketId}/record":{"get":{"tags":["Work ledger"],"summary":"Read current ticket without revision bodies","description":"Same scoped ticket authority as legacy detail. historyIncluded=false; omitted revisions do not imply empty history. No query parameters or graph fallback.","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"ticketId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Current ticket with historyIncluded=false"},"400":{"description":"Unsupported filters"},"401":{"description":"API key required"},"403":{"description":"Scope required"},"404":{"description":"Ticket not found"},"503":{"description":"Explicit budget or timeout failure; no partial result"}}}},"/tickets/{ticketId}/history":{"get":{"tags":["Work ledger"],"summary":"Page visible immutable ticket revisions","description":"Oldest-first revisionNumber/revisionId order. data contains ticketId, solutionId, items, previous visible revision, total, limit, offset, hasMore and nextOffset. Counts and previous exclude inaccessible revisions. Defaults to ten rich revisions; follow nextOffset until complete. Byte/timeout failures remain errors, not empty pages.","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"ticketId","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":25,"default":10}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":100000,"default":0}}],"responses":{"200":{"description":"Authorized revision page"},"400":{"description":"Invalid page filters"},"401":{"description":"API key required"},"403":{"description":"Scope required"},"404":{"description":"Ticket not found"},"503":{"description":"Explicit budget or timeout failure; no partial result"}}}},"/change-capsules":{"get":{"tags":["Work ledger"],"summary":"List change capsules visible to the scoped API key","description":"Returns change capsule state for the visible workspace, solution, or project scope. Project-scoped keys only receive capsules that reference their project through source refs, evidence, commits, repositories, or payload metadata.","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"solutionId","in":"query","required":false,"schema":{"type":"string"}},{"name":"projectId","in":"query","required":false,"schema":{"type":"string"}},{"name":"query","in":"query","required":false,"schema":{"type":"string"}},{"name":"outcome","in":"query","required":false,"schema":{"type":"string"}},{"name":"hasExactDiff","in":"query","required":false,"schema":{"type":"boolean"}},{"name":"limit","in":"query","required":false,"schema":{"type":"string"}},{"name":"offset","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Change capsule summaries"},"400":{"description":"Scope mismatch"},"401":{"description":"ClearTrace API key required"},"403":{"description":"API key scope required"},"404":{"description":"Scope object not found"}}}},"/change-capsules/{changeCapsuleId}":{"get":{"tags":["Work ledger"],"summary":"Get a change capsule visible to the scoped API key","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"changeCapsuleId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Change capsule detail"},"401":{"description":"ClearTrace API key required"},"403":{"description":"API key scope required"},"404":{"description":"Change capsule not found"}}}},"/change-capsules/{changeCapsuleId}/snapshot":{"get":{"tags":["Work ledger"],"summary":"Get commit, file, and architecture-diff evidence for a change","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"changeCapsuleId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Change snapshot"},"401":{"description":"ClearTrace API key required"},"403":{"description":"API key scope required"},"404":{"description":"Change snapshot not found"}}}},"/change-capsules/{changeCapsuleId}/file-changes/{fileChangeId}/diff":{"get":{"tags":["Work ledger"],"summary":"Read one retained exact file diff as structured hunks","description":"Returns authorized line-level Git unified-diff evidence without exposing the private object-storage URI. Older metadata-only records return an explicit unavailable response.","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"changeCapsuleId","in":"path","required":true,"schema":{"type":"string"}},{"name":"fileChangeId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Integrity-verified structured file diff","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileDiffReadResponse"}}}},"401":{"description":"ClearTrace API key required"},"403":{"description":"API key scope required"},"404":{"description":"Change or exact-diff artifact not available"},"410":{"description":"Recorded diff artifact is no longer available"}}}},"/working-plans":{"get":{"tags":["Working plans"],"summary":"List working plans visible to the scoped API key","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"visibility","in":"query","required":false,"schema":{"type":"string"}},{"name":"scopeType","in":"query","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string"}},{"name":"solutionId","in":"query","required":false,"schema":{"type":"string"}},{"name":"projectId","in":"query","required":false,"schema":{"type":"string"}},{"name":"ticketId","in":"query","required":false,"schema":{"type":"string"}},{"name":"changeCapsuleId","in":"query","required":false,"schema":{"type":"string"}},{"name":"sourceRef","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Working plan summaries"},"401":{"description":"ClearTrace API key required"},"403":{"description":"API key scope required"}}},"post":{"tags":["Working plans"],"summary":"Create a private or team-visible working plan","security":[{"scopedMachineApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkingPlanCreateRequest"}}}},"responses":{"201":{"description":"Working plan created"},"400":{"description":"Invalid working plan"},"401":{"description":"ClearTrace API key required"},"403":{"description":"API key scope required"}}}},"/working-plans/resolve":{"get":{"tags":["Working plans"],"summary":"Resolve the active working plan an assistant should follow for a scope","description":"Returns applicable visible plans ordered by specificity. Assistants should read this before multi-step work and follow primaryPlan unless the user changes direction.","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"visibility","in":"query","required":false,"schema":{"type":"string"}},{"name":"scopeType","in":"query","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string"}},{"name":"solutionId","in":"query","required":false,"schema":{"type":"string"}},{"name":"projectId","in":"query","required":false,"schema":{"type":"string"}},{"name":"ticketId","in":"query","required":false,"schema":{"type":"string"}},{"name":"changeCapsuleId","in":"query","required":false,"schema":{"type":"string"}},{"name":"sourceRef","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Resolved working-plan selection"},"400":{"description":"Scope mismatch"},"401":{"description":"ClearTrace API key required"},"403":{"description":"API key scope required"},"404":{"description":"Requested scope object not found"}}}},"/working-plans/{workingPlanId}":{"get":{"tags":["Working plans"],"summary":"Get a working plan","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"workingPlanId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Working plan detail"},"401":{"description":"ClearTrace API key required"},"403":{"description":"API key scope required"},"404":{"description":"Working plan not found"}}},"patch":{"tags":["Working plans"],"summary":"Update a working plan","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"workingPlanId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkingPlanUpdateRequest"}}}},"responses":{"200":{"description":"Working plan updated"},"400":{"description":"Invalid update"},"401":{"description":"ClearTrace API key required"},"403":{"description":"API key scope required"},"404":{"description":"Working plan not found"},"409":{"description":"Version conflict"}}}},"/working-plans/{workingPlanId}/events":{"post":{"tags":["Working plans"],"summary":"Append a working-plan event, decision, step, or status change","description":"Append a user-approved progress event. Assistants should include expectedVersion from the latest plan read so stale updates return working_plan_version_conflict instead of overwriting newer plan state.","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"workingPlanId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WorkingPlanEventRequest"}}}},"responses":{"200":{"description":"Working plan updated"},"400":{"description":"Invalid event"},"401":{"description":"ClearTrace API key required"},"403":{"description":"API key scope required"},"404":{"description":"Working plan not found"},"409":{"description":"Version conflict"}}}},"/project-kits":{"get":{"tags":["Project context"],"summary":"List project-kit readiness for the authenticated workspace","security":[{"scopedMachineApiKey":[]}],"responses":{"200":{"description":"Project kit list with release, bundle, and installed-evidence state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectKitLifecycleListResponse"}}}},"401":{"description":"ClearTrace API key required"},"403":{"description":"API key scope required"}}}},"/project-kits/{projectId}":{"get":{"tags":["Project context"],"summary":"Get project-kit detail for a project","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Project kit detail with actionable lifecycle state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectKitLifecycleDetailResponse"}}}},"401":{"description":"ClearTrace API key required"},"403":{"description":"API key scope required"},"404":{"description":"Project not found"}}}},"/project-kits/{projectId}/download":{"get":{"tags":["Project context"],"summary":"Download a review-first, integrity-addressed five-file project-kit bundle","description":"Returns the exact five-file JSON bundle consumed by the local preview/apply installer. The API and MCP remain read-only with respect to local project files. Download requires tenant and project identity; Git repository metadata is optional provenance.","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}},{"name":"version","in":"query","required":false,"schema":{"type":"string","pattern":"^[0-9]+\\.[0-9]+\\.[0-9]+(?:[-+][A-Za-z0-9.-]+)?$"},"description":"Optional known supported immutable release. Omit to download the current published release."}],"responses":{"200":{"description":"Versioned project-kit bundle with canonical content hashes for the five allowed .cleartrace files","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ProjectKitBundleResponse"}}}},"400":{"description":"Requested project-kit version is unknown or unsupported"},"401":{"description":"ClearTrace API key required"},"403":{"description":"API key scope required"},"404":{"description":"Project not found"},"409":{"description":"Project kit needs explicit tenant/project identity or a published supported release before download"}}}},"/projects/{projectId}/scanner-config":{"get":{"tags":["Project context"],"summary":"Get scanner configuration for a project","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Scanner config"},"401":{"description":"ClearTrace API key required"},"403":{"description":"API key scope required"},"404":{"description":"Project not found"}}}},"/projects/{projectId}/foundation":{"get":{"tags":["Project context"],"summary":"Get project foundation references","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Foundation references"},"401":{"description":"ClearTrace API key required"},"403":{"description":"API key scope required"},"404":{"description":"Project not found"}}}},"/projects/{projectId}/context":{"get":{"tags":["Project context"],"summary":"Get assistant-ready project context","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Project context bundle"},"401":{"description":"ClearTrace API key required"},"403":{"description":"API key scope required"},"404":{"description":"Project not found"}}}},"/projects/{projectId}/ticket-participants":{"get":{"tags":["Work ledger"],"summary":"List active human users eligible for ticket ownership in a project","description":"Returns safe participant IDs for assignees and followers. Use participantId exactly as returned; email addresses are never participant IDs and are not returned.","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Eligible ticket participants"},"401":{"description":"ClearTrace API key required"},"403":{"description":"API key or project access required"},"404":{"description":"Project not found"},"409":{"description":"Catalog changed during the read; retry the read"},"503":{"description":"Read budget or timeout exceeded; no partial directory returned"}}}},"/projects/{projectId}/ticket-participants/search":{"post":{"tags":["Work ledger"],"summary":"Resolve a named human to a canonical ticket participant ID","description":"Matches display names case-insensitively and partial, but matches emails only exactly. Responses contain canonical participant IDs and masked email hints; they never expose a tenant email directory.","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["query"],"properties":{"query":{"type":"string","minLength":2,"maxLength":160}},"additionalProperties":false}}}},"responses":{"200":{"description":"Canonical participant candidates"},"400":{"description":"Invalid search"},"401":{"description":"ClearTrace API key required"},"403":{"description":"API key or project access required"},"404":{"description":"Project not found"},"409":{"description":"Catalog changed during the read; retry the read"},"503":{"description":"Read budget or timeout exceeded; no partial search returned"}}}},"/projects/{projectId}/agent-spec":{"get":{"tags":["Project context"],"summary":"Get project-specific assistant agent instructions","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Project agent spec"},"401":{"description":"ClearTrace API key required"},"403":{"description":"API key scope required"},"404":{"description":"Project not found"}}}},"/projects/{projectId}/change-state":{"get":{"tags":["Project context"],"summary":"Get current tickets, findings, change capsules, evidence, and pushes relevant to a project","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Project change state"},"401":{"description":"ClearTrace API key required"},"403":{"description":"API key scope required"},"404":{"description":"Project not found"}}}},"/projects/{projectId}/components":{"get":{"tags":["Project context"],"summary":"Get component summaries for a project","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Component summaries"},"401":{"description":"ClearTrace API key required"},"403":{"description":"API key scope required"},"404":{"description":"Project not found"}}}},"/projects/{projectId}/component-manifests":{"get":{"tags":["Project context"],"summary":"Get component manifests for a project","security":[{"scopedMachineApiKey":[]}],"parameters":[{"name":"projectId","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Component manifests"},"401":{"description":"ClearTrace API key required"},"403":{"description":"API key scope required"},"404":{"description":"Project not found"}}}},"/package-lint":{"post":{"tags":["Validation"],"summary":"Validate an assistant-produced payload without ingesting it","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Validation result"}}}},"/tickets/validate":{"post":{"tags":["Validation"],"summary":"Validate a ticket push envelope without ingesting it","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TicketPushEnvelope"},"examples":{"ticket":{"summary":"Ticket push envelope","value":{"contractId":"delivery-to-changehub-push-v1","pushType":"ticket","sourceProjectId":"project-api","solutionId":"solution-cleartrace","environmentId":null,"objectId":"ticket-project-api-routing-001","createdAt":"2026-07-08T12:00:00.000Z","sourceRefs":["project:project-api","change-capsule:change-api-routing-001"],"evidenceRefs":[],"payload":{"title":"Wire API routing task to scoped provider selection","status":"open","priority":"medium","severity":"low","intent":{"summary":"Track a durable delivery task that needs follow-up, verification, or ownership."},"scope":{"sourceProjectId":"project-api","projectIds":["project-api"]},"verification":{"status":"pending"},"ownership":{"assignees":[{"participantType":"agent","participantId":"claude-project-api-implementation","displayName":"Claude implementation account"}],"followers":[{"participantType":"user","participantId":"user-tester-1","displayName":"Primary tester"}]}}}}}}}},"responses":{"200":{"description":"Validation result"}}}},"/change-capsules/validate":{"post":{"tags":["Validation"],"summary":"Validate a change-capsule push envelope without ingesting it","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ChangeCapsulePushEnvelope"},"examples":{"changeCapsule":{"summary":"Change-capsule push envelope","value":{"contractId":"delivery-to-changehub-push-v1","pushType":"change_capsule","sourceProjectId":"project-api","solutionId":"solution-cleartrace","environmentId":null,"objectId":"change-api-routing-001","createdAt":"2026-07-08T12:00:00.000Z","sourceRefs":["project:project-api","commit:abc123"],"evidenceRefs":["evidence:test-smoke-api-routing"],"payload":{"title":"Add scoped AI routing enforcement","summary":"Records the implementation, affected components, validation evidence, and related tickets for one coherent change.","status":"proposed","impact":{"projectIds":["project-api"],"components":["ai-integration-api"]},"verification":{"status":"pending","evidenceRefs":["evidence:test-smoke-api-routing"]}}}}}}}},"responses":{"200":{"description":"Validation result"}}}},"/ingest/packages/validate":{"post":{"tags":["Validation"],"summary":"Validate a package payload before ingestion","security":[{"scopedMachineApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"200":{"description":"Validation result"},"401":{"description":"ClearTrace API key required"},"403":{"description":"push:package scope required"}}}},"/ingest/packages":{"post":{"tags":["Machine ingestion"],"summary":"Materialize an approved immutable ClearTrace package","description":"Stores package identity and derived commit, file, change-capsule, current-state, history, and diff records. Identical retries are idempotent; conflicting reuse of a package id is rejected.","security":[{"scopedMachineApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClearTracePackage"}}}},"responses":{"200":{"description":"Package was already materialized with identical content"},"202":{"description":"Package materialized"},"400":{"description":"Invalid package"},"401":{"description":"ClearTrace API key required"},"403":{"description":"push:package scope or catalog grant required"},"409":{"description":"Immutable package, commit, state, or baseline conflict"}}}},"/ingest/write-sets/preview":{"post":{"tags":["Validation"],"summary":"Preview one authenticated, projection-aware push write set","description":"Validates API-key grants, catalog references, human participant IDs, environment mapping, and current-versus-historical projection behavior. Current tickets may explicitly declare payload.scope.findingReferenceRepairs with fromFindingId, toFindingId and reason for verified missing-finding-prefix references. The original ID must be absent and the canonical target registered in the same solution. Returns the exact normalized write set and one planHash without storing data.","security":[{"scopedMachineApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushWriteSetRequest"}}}},"responses":{"200":{"description":"Projection-aware write-set plan; inspect canSubmit and diagnostics"},"401":{"description":"ClearTrace API key required"},"403":{"description":"API key scope required for one or more writes"}}}},"/ingest/write-sets":{"post":{"tags":["Machine ingestion"],"summary":"Atomically submit an approved normalized push write set","description":"Revalidates the current catalog and projections against the approved planHash. Every typed write materializes in one transaction or the complete write set rolls back.","security":[{"scopedMachineApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PushWriteSetSubmitRequest"}}}},"responses":{"202":{"description":"All writes accepted and typed projections created"},"400":{"description":"Invalid or unmaterializable write set"},"401":{"description":"ClearTrace API key required"},"403":{"description":"API key scope required"},"409":{"description":"Approved plan is stale because the write set or current projection boundary changed"}}}},"/ingest/task-closeouts/preview":{"post":{"tags":["Validation"],"summary":"Preview one complete multi-project task closeout","description":"Validates every task-level change package and the related typed write set, exposes each exact Git base/head/commit set, and returns one approval planHash. Child package, write-set, and rendered-document hashes are diagnostics rather than additional approval gates. Change summaries: 1–4000 trimmed UTF-16 code units. Local CLI capsule IDs and titles: 1–500; each changed-file path: 1–2000. These are summary/metadata limits, not diff or evidence limits. Keep the concise overview in summary and retain detailed analysis in evidence. Invalid text returns field, actualLength, minLength, maxLength, unit and recoveryAction=fix_request; never truncate automatically or submit a failed preview.","security":[{"scopedMachineApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCloseoutRequest"}}}},"responses":{"200":{"description":"One task-closeout plan with normalizedCloseout, exact Git ranges, diagnostics, and one approval hash"},"401":{"description":"ClearTrace API key required"},"403":{"description":"API key scope required for one or more packages or writes"}}}},"/ingest/task-closeouts":{"post":{"tags":["Machine ingestion"],"summary":"Submit one approved multi-project task closeout","description":"PostgreSQL revalidates the approved typed projections under lock and atomically materializes immutable packages and typed writes. history_only preserves architecture evidence without advancing current heads. Identical accepted retries reuse approval; changed semantic content returns 409. Historical mode is unavailable on nontransactional stores.","security":[{"scopedMachineApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskCloseoutSubmitRequest"}}}},"responses":{"200":{"description":"The exact closeout was already applied"},"202":{"description":"The complete closeout was applied"},"400":{"description":"Invalid closeout or approval hash"},"401":{"description":"ClearTrace API key required"},"403":{"description":"API key scope required"},"409":{"description":"Approved closeout is stale or conflicts with current state"}}}}},"components":{"securitySchemes":{"scopedMachineApiKey":{"type":"apiKey","in":"header","name":"X-ClearTrace-Api-Key","description":"Scoped ClearTrace machine key for AI-integration reads and ingestion. This is not an OpenAI, Azure, Anthropic, or Gemini provider key."}},"schemas":{"PushEnvelope":{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://api.cleartrace.dev/ai-integration/v1/schemas/push-envelope.schema.json","title":"ClearTrace Push Envelope","type":"object","required":["contractId","pushType","sourceProjectId","solutionId","objectId","createdAt","payload"],"properties":{"contractId":{"type":"string"},"pushType":{"type":"string","enum":["test_run","finding","ticket","change_capsule"]},"sourceProjectId":{"type":"string"},"solutionId":{"type":"string"},"environmentId":{"type":["string","null"]},"objectId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"sourceRefs":{"type":"array","items":{"type":"string"}},"evidenceRefs":{"type":"array","items":{"type":"string"}},"payload":{"type":"object"}},"additionalProperties":true},"TicketPushEnvelope":{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://api.cleartrace.dev/ai-integration/v1/schemas/ticket-push-envelope.schema.json","title":"ClearTrace Ticket Push Envelope","type":"object","required":["contractId","pushType","sourceProjectId","solutionId","objectId","createdAt","payload"],"properties":{"contractId":{"type":"string"},"pushType":{"type":"string","const":"ticket"},"sourceProjectId":{"type":"string"},"solutionId":{"type":"string"},"environmentId":{"type":["string","null"]},"objectId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"sourceRefs":{"type":"array","items":{"type":"string"}},"evidenceRefs":{"type":"array","items":{"type":"string"}},"payload":{"type":"object","required":["title","status"],"properties":{"title":{"type":"string","minLength":1},"status":{"type":"string","minLength":1},"priority":{"type":["string","null"]},"severity":{"type":["string","null"]},"intent":{"type":"object","description":"Why this ticket exists and what outcome it tracks. Every field is optional.","properties":{"summary":{"type":"string","maxLength":4000,"description":"What the ticket is about, in one or two sentences."},"reason":{"type":["string","null"],"maxLength":8000,"description":"Why it matters or why it was requested. Optional; leave it out when nobody said."},"impact":{"type":["string","object","null"],"description":"Who or what is affected."},"resolution":{"type":["string","object","null"],"description":"How it was or will be resolved, once known."},"ownerDecision":{"type":["string","object","null"],"description":"A decision the owner took about this ticket."},"openQuestions":{"type":"array","maxItems":50,"items":{"type":"string","maxLength":2000},"description":"Doubts still open, one string each."},"discoveredBy":{"type":["string","object","null"],"description":"Who or what found it."},"requestedBy":{"type":["string","object","null"],"description":"Who asked for it."}},"additionalProperties":true},"scope":{"type":"object","description":"Solution, project, repository, component, ticket, finding, or change-capsule scope."},"verification":{"type":"object","description":"Current validation state. Send only the current state: ClearTrace keeps every earlier revision as ticket history.","properties":{"status":{"type":"string","description":"Verification state in the producer's words."},"acceptance":{"description":"What has to be true to accept the work."},"repro":{"description":"How to reproduce the problem."},"plannedRetest":{"description":"The retest the reporter plans once a fix is delivered."},"deliveryUpdate":{"type":"object","additionalProperties":false,"required":["contractId","kind","summary"],"properties":{"contractId":{"const":"cleartrace-ticket-delivery-update-v1"},"kind":{"enum":["implementation","retest","closure","administrative","status"]},"summary":{"type":"string","minLength":1,"maxLength":8000},"implementationDetails":{"type":"string","minLength":1,"maxLength":16000},"packageRefs":{"type":"array","maxItems":100,"uniqueItems":true,"items":{"type":"string","pattern":"^package:.+"}},"checks":{"type":"array","maxItems":100,"items":{"type":"object","additionalProperties":false,"required":["name","result","evidenceRefs"],"properties":{"name":{"type":"string","minLength":1},"result":{"enum":["passed","failed","not_run"]},"evidenceRefs":{"type":"array","minItems":1,"items":{"type":"string","minLength":1}}}}},"codeEvidence":{"type":"object","additionalProperties":false,"required":["status"],"properties":{"status":{"enum":["included","unavailable","not_applicable"]},"reason":{"type":"string","minLength":1}}},"retest":{"type":"object","additionalProperties":false,"required":["status"],"properties":{"status":{"enum":["pending","passed","failed","not_required"]},"reason":{"type":"string","minLength":1},"evidenceRefs":{"type":"array","minItems":1,"items":{"type":"string","minLength":1}},"observed":{"type":"array","maxItems":50,"items":{"type":"string","minLength":1,"maxLength":2000},"description":"What the retest observed, one finding per entry. Replaces the previous retest; earlier ones stay in ticket history."},"build":{"type":"string","minLength":1,"maxLength":200,"description":"Build or deployment the retest ran against."},"testedAt":{"type":"string","format":"date-time"},"method":{"type":"string","minLength":1,"maxLength":1000,"description":"How it was tested."}}},"administrativeReason":{"type":"string","minLength":1,"maxLength":8000}}}}},"ownership":{"type":"object","description":"Ownership published by the project workflow. ClearTrace records it but does not create a parallel assignment decision.","properties":{"assignees":{"type":"array","maxItems":50,"items":{"type":"object","required":["participantType","participantId"],"properties":{"participantType":{"type":"string","enum":["user","agent"]},"participantId":{"type":"string","minLength":1,"maxLength":200,"description":"For a user, use the exact tenant userId returned by the project ticket-participant directory; never use email. For an agent, use its stable actor connectionId."},"displayName":{"type":["string","null"],"minLength":1,"maxLength":200}},"allOf":[{"if":{"required":["participantType"],"properties":{"participantType":{"const":"user"}}},"then":{"properties":{"participantId":{"pattern":"^user-"}}}}],"additionalProperties":false}},"followers":{"type":"array","maxItems":50,"items":{"type":"object","required":["participantType","participantId"],"properties":{"participantType":{"type":"string","enum":["user","agent"]},"participantId":{"type":"string","minLength":1,"maxLength":200,"description":"For a user, use the exact tenant userId returned by the project ticket-participant directory; never use email. For an agent, use its stable actor connectionId."},"displayName":{"type":["string","null"],"minLength":1,"maxLength":200}},"allOf":[{"if":{"required":["participantType"],"properties":{"participantType":{"const":"user"}}},"then":{"properties":{"participantId":{"pattern":"^user-"}}}}],"additionalProperties":false}}},"additionalProperties":false}},"additionalProperties":true}},"additionalProperties":true,"description":"A delivery-to-changehub-push-v1 envelope that creates or updates a durable ClearTrace ticket/work item.","examples":[{"contractId":"delivery-to-changehub-push-v1","pushType":"ticket","sourceProjectId":"project-api","solutionId":"solution-cleartrace","environmentId":null,"objectId":"ticket-project-api-routing-001","createdAt":"2026-07-08T12:00:00.000Z","sourceRefs":["project:project-api","change-capsule:change-api-routing-001"],"evidenceRefs":[],"payload":{"title":"Wire API routing task to scoped provider selection","status":"open","priority":"medium","severity":"low","intent":{"summary":"Track a durable delivery task that needs follow-up, verification, or ownership."},"scope":{"sourceProjectId":"project-api","projectIds":["project-api"]},"verification":{"status":"pending"},"ownership":{"assignees":[{"participantType":"agent","participantId":"claude-project-api-implementation","displayName":"Claude implementation account"}],"followers":[{"participantType":"user","participantId":"user-tester-1","displayName":"Primary tester"}]}}}]},"ChangeCapsulePushEnvelope":{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://api.cleartrace.dev/ai-integration/v1/schemas/change-capsule-push-envelope.schema.json","title":"ClearTrace Change Capsule Push Envelope","type":"object","required":["contractId","pushType","sourceProjectId","solutionId","objectId","createdAt","payload"],"properties":{"contractId":{"type":"string"},"pushType":{"type":"string","const":"change_capsule"},"sourceProjectId":{"type":"string"},"solutionId":{"type":"string"},"environmentId":{"type":["string","null"]},"objectId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"sourceRefs":{"type":"array","items":{"type":"string"}},"evidenceRefs":{"type":"array","items":{"type":"string"}},"payload":{"type":"object","required":["title","summary"],"properties":{"title":{"type":"string","minLength":1},"summary":{"type":"string","minLength":1},"status":{"type":["string","null"]},"impact":{"type":"object","description":"Structured affected project, repository, component, spec, test, data, or API impact."},"verification":{"type":"object","description":"Validation, test, review, or rollout state for the change."}},"additionalProperties":true}},"additionalProperties":true,"description":"A delivery-to-changehub-push-v1 envelope that records an implemented or proposed change across projects, repos, specs, tests, evidence, or tickets.","examples":[{"contractId":"delivery-to-changehub-push-v1","pushType":"change_capsule","sourceProjectId":"project-api","solutionId":"solution-cleartrace","environmentId":null,"objectId":"change-api-routing-001","createdAt":"2026-07-08T12:00:00.000Z","sourceRefs":["project:project-api","commit:abc123"],"evidenceRefs":["evidence:test-smoke-api-routing"],"payload":{"title":"Add scoped AI routing enforcement","summary":"Records the implementation, affected components, validation evidence, and related tickets for one coherent change.","status":"proposed","impact":{"projectIds":["project-api"],"components":["ai-integration-api"]},"verification":{"status":"pending","evidenceRefs":["evidence:test-smoke-api-routing"]}}}]},"PushWriteSetRequest":{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://api.cleartrace.dev/ai-integration/v1/schemas/push-write-set.schema.json","title":"ClearTrace Push Write Set","description":"One coherent, authenticated group of related typed projection writes reviewed under a single approval hash.","type":"object","required":["contractId","writes"],"properties":{"contractId":{"const":"cleartrace-push-write-set-v1"},"writes":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","required":["envelope"],"properties":{"envelope":{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://api.cleartrace.dev/ai-integration/v1/schemas/push-envelope.schema.json","title":"ClearTrace Push Envelope","type":"object","required":["contractId","pushType","sourceProjectId","solutionId","objectId","createdAt","payload"],"properties":{"contractId":{"type":"string"},"pushType":{"type":"string","enum":["test_run","finding","ticket","change_capsule"]},"sourceProjectId":{"type":"string"},"solutionId":{"type":"string"},"environmentId":{"type":["string","null"]},"objectId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"sourceRefs":{"type":"array","items":{"type":"string"}},"evidenceRefs":{"type":"array","items":{"type":"string"}},"payload":{"type":"object"}},"additionalProperties":true},"projectionIntent":{"type":"string","enum":["current","historical"],"default":"current","description":"Use current for ordinary create/update work. Historical is explicit and currently supported only for an older ticket revision."}},"additionalProperties":false}}},"additionalProperties":false},"PushWriteSetSubmitRequest":{"type":"object","required":["writeSet","planHash","approved"],"properties":{"writeSet":{"$ref":"#/components/schemas/PushWriteSetRequest"},"planHash":{"type":"string","pattern":"^sha256:[a-f0-9]{64}$"},"approved":{"const":true}},"additionalProperties":false},"LocalTaskCloseoutManifest":{"type":"object","description":"Local CLI manifest; not an HTTP submission payload. Change summaries: 1–4000 trimmed UTF-16 code units. Local CLI capsule IDs and titles: 1–500; each changed-file path: 1–2000. These are summary/metadata limits, not diff or evidence limits. Keep the concise overview in summary and retain detailed analysis in evidence. Invalid text returns field, actualLength, minLength, maxLength, unit and recoveryAction=fix_request; never truncate automatically or submit a failed preview.","properties":{"contractId":{"const":"cleartrace-local-task-closeout-v1"},"repositories":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","properties":{"changeCapsuleId":{"type":"string","minLength":1,"maxLength":500},"title":{"type":"string","minLength":1,"maxLength":500},"summary":{"type":"string","minLength":1,"maxLength":4000},"changedFiles":{"type":"array","items":{"type":"string","minLength":1,"maxLength":2000}}}}}}},"PackageInputDiagnostic":{"type":"object","required":["field","actualLength","minLength","maxLength","unit","recoveryAction"],"properties":{"field":{"enum":["changeCapsuleId","title","summary","changedFile"]},"actualLength":{"type":"integer","minimum":0},"minLength":{"const":1},"maxLength":{"type":"integer","minimum":1},"unit":{"const":"utf16_code_units"},"recoveryAction":{"const":"fix_request"}}},"TaskCloseoutRequest":{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://api.cleartrace.dev/ai-integration/v1/schemas/task-closeout.schema.json","title":"ClearTrace Task Closeout","description":"Every task-level repository change package and its related typed writes under one approval boundary.","type":"object","required":["contractId","packages"],"properties":{"contractId":{"const":"cleartrace-task-closeout-v1"},"architectureDisposition":{"type":"string","enum":["current","history_only"],"description":"Defaults to current. history_only retains captured evidence without advancing architecture heads or component/spec catalogs; requires a new preview approval and transactional storage."},"packages":{"type":"array","minItems":1,"maxItems":20,"items":{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://api.cleartrace.dev/ai-integration/v1/schemas/changehub-package.schema.json","title":"ClearTrace Package","type":"object","required":["contractId","packageId","packageType","version","createdAt","scope","actor","source","contents"],"properties":{"contractId":{"type":"string","const":"changehub-package-v1"},"packageId":{"type":"string"},"packageType":{"type":"string"},"version":{"type":"integer","minimum":1},"createdAt":{"type":"string","format":"date-time"},"scope":{"type":"object"},"actor":{"type":"object"},"source":{"type":"object"},"contents":{"type":"object","properties":{"change":{"type":"object","required":["contractId","version","summary","categories","affectedObjects","classificationSource","existingObjectResolution"],"properties":{"contractId":{"const":"cleartrace-change-evidence-v1"},"version":{"const":1},"summary":{"type":"string","minLength":1,"maxLength":4000,"description":"Concise overview, 1–4000 trimmed UTF-16 code units; detailed analysis belongs in evidence. This is not a code/diff size limit.","x-length-unit":"utf16_code_units"},"categories":{"type":"array","minItems":1,"maxItems":11,"uniqueItems":true,"items":{"type":"string","enum":["application","api","database","infrastructure","configuration","test","specification","documentation","project_kit","security","other"]}},"affectedObjects":{"type":"array","maxItems":2000,"items":{"type":"object","required":["stateKind","sourceScopeKey","objectKey","changeType","role","confidence"],"properties":{"stateKind":{"type":"string","enum":["infrastructure","data_model","data_flow"]},"sourceScopeKey":{"type":"string","pattern":"^(?:project|repository):[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$"},"objectKey":{"type":"string","minLength":1,"maxLength":1000},"changeType":{"type":"string","enum":["added","modified","removed","affected"]},"role":{"type":"string","enum":["primary","dependency","related"]},"confidence":{"type":"number","minimum":0,"maximum":1}},"additionalProperties":false}},"classificationSource":{"type":"string","enum":["deterministic","agent_enriched","mixed"]},"existingObjectResolution":{"const":"stable_identity_first"}},"additionalProperties":false},"evidenceProfile":{"type":"object","required":["contractId","version","requested","reported"],"properties":{"contractId":{"const":"cleartrace-delivery-evidence-profile-v1"},"version":{"const":1},"requested":{"type":"object","properties":{"change_detail":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"system_architecture":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"cloud_and_deployment":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"data_model":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"data_flow":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"tests":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"specifications":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]}},"additionalProperties":false},"reported":{"type":"object","properties":{"change_detail":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"system_architecture":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"cloud_and_deployment":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"data_model":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"data_flow":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"tests":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"specifications":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]}},"additionalProperties":false}},"additionalProperties":false},"evidenceRuntime":{"type":"object","required":["contractId","version","sourceMode","localGitAvailable","exactDiffAvailable","changeBasis","downgrades"],"properties":{"contractId":{"const":"cleartrace-evidence-runtime-v1"},"version":{"const":1},"sourceMode":{"type":"string","enum":["git","filesystem"]},"localGitAvailable":{"type":"boolean"},"exactDiffAvailable":{"type":"boolean"},"workingTreeScope":{"type":"object","additionalProperties":false,"required":["mode","selectedFiles"],"properties":{"mode":{"enum":["committed_only","selected_files","all_eligible_files"]},"selectedFiles":{"type":"array","uniqueItems":true,"items":{"type":"string","minLength":1}}}},"changeBasis":{"type":"string","enum":["git_working_tree","git_commit_range","filesystem_reported_paths","filesystem_current_state"]},"downgrades":{"type":"array","items":{"type":"object","required":["domain","requested","effective","reason"],"properties":{"domain":{"type":"string","enum":["change_detail","system_architecture","cloud_and_deployment","data_model","data_flow","tests","specifications"]},"requested":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"effective":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"reason":{"type":"string","enum":["local_git_required_for_exact_diff","available_evidence_below_requested_level"]}},"additionalProperties":false}}},"additionalProperties":false},"privacyMode":{"type":"string","enum":["reference_only","metadata_summary","snapshot_text","artifact_file"]},"patchText":{"type":"string","minLength":1,"description":"Git unified diff retained only when the approved privacy mode and evidence profile allow exact change detail."}},"additionalProperties":true},"links":{"type":"array","items":{"type":"object"}}},"additionalProperties":true}},"writeSet":{"anyOf":[{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://api.cleartrace.dev/ai-integration/v1/schemas/push-write-set.schema.json","title":"ClearTrace Push Write Set","description":"One coherent, authenticated group of related typed projection writes reviewed under a single approval hash.","type":"object","required":["contractId","writes"],"properties":{"contractId":{"const":"cleartrace-push-write-set-v1"},"writes":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","required":["envelope"],"properties":{"envelope":{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://api.cleartrace.dev/ai-integration/v1/schemas/push-envelope.schema.json","title":"ClearTrace Push Envelope","type":"object","required":["contractId","pushType","sourceProjectId","solutionId","objectId","createdAt","payload"],"properties":{"contractId":{"type":"string"},"pushType":{"type":"string","enum":["test_run","finding","ticket","change_capsule"]},"sourceProjectId":{"type":"string"},"solutionId":{"type":"string"},"environmentId":{"type":["string","null"]},"objectId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"sourceRefs":{"type":"array","items":{"type":"string"}},"evidenceRefs":{"type":"array","items":{"type":"string"}},"payload":{"type":"object"}},"additionalProperties":true},"projectionIntent":{"type":"string","enum":["current","historical"],"default":"current","description":"Use current for ordinary create/update work. Historical is explicit and currently supported only for an older ticket revision."}},"additionalProperties":false}}},"additionalProperties":false},{"type":"null"}]},"operationRuns":{"type":"array","maxItems":50,"description":"Runs of operations done in this task (deploy, migrate, clone, rotate, backup, restore...). Covered by the closeout planHash; identical retries store nothing twice. Release deployments stay in the release ledger.","items":{"type":"object","required":["kind","target","runs","startedAt","outcome","ranBy"],"additionalProperties":false,"properties":{"operation":{"anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}],"description":"Declared operation name from architecture/cleartrace-operations.json, or null."},"kind":{"type":"string","enum":["provision","deploy","migrate","rotate","backup","restore","clone","seed","check","other"]},"target":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}:[A-Za-z0-9][A-Za-z0-9._-]{0,63}(:[A-Za-z0-9][A-Za-z0-9._-]{0,63})?$","description":"<environment>:<service>[:<database>]"},"runs":{"type":"string","minLength":1,"maxLength":500,"description":"Repository-relative script, workflow or runbook path."},"startedAt":{"type":"string","format":"date-time"},"finishedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"outcome":{"type":"string","enum":["succeeded","failed","partial","cancelled"]},"ranBy":{"type":"string","enum":["agent","user","ci"]},"actor":{"anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}],"description":"Name, handle or tool; never an email."},"evidenceRefs":{"type":"array","maxItems":20,"items":{"type":"string","minLength":1,"maxLength":500}},"notes":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"description":"No secrets, keys, connection strings or local paths."},"projectId":{"anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}],"description":"Required only when the closeout has packages from several projects."}}}}},"additionalProperties":false},"TaskCloseoutSubmitRequest":{"type":"object","required":["closeout","planHash","approved"],"properties":{"closeout":{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://api.cleartrace.dev/ai-integration/v1/schemas/task-closeout.schema.json","title":"Normalized ClearTrace Task Closeout","description":"Every task-level repository change package and its related typed writes under one approval boundary.","type":"object","required":["contractId","packages","guard"],"properties":{"contractId":{"const":"cleartrace-task-closeout-v1"},"architectureDisposition":{"type":"string","enum":["current","history_only"],"description":"Defaults to current. history_only retains captured evidence without advancing architecture heads or component/spec catalogs; requires a new preview approval and transactional storage."},"packages":{"type":"array","minItems":1,"maxItems":20,"items":{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://api.cleartrace.dev/ai-integration/v1/schemas/changehub-package.schema.json","title":"ClearTrace Package","type":"object","required":["contractId","packageId","packageType","version","createdAt","scope","actor","source","contents"],"properties":{"contractId":{"type":"string","const":"changehub-package-v1"},"packageId":{"type":"string"},"packageType":{"type":"string"},"version":{"type":"integer","minimum":1},"createdAt":{"type":"string","format":"date-time"},"scope":{"type":"object"},"actor":{"type":"object"},"source":{"type":"object"},"contents":{"type":"object","properties":{"change":{"type":"object","required":["contractId","version","summary","categories","affectedObjects","classificationSource","existingObjectResolution"],"properties":{"contractId":{"const":"cleartrace-change-evidence-v1"},"version":{"const":1},"summary":{"type":"string","minLength":1,"maxLength":4000,"description":"Concise overview, 1–4000 trimmed UTF-16 code units; detailed analysis belongs in evidence. This is not a code/diff size limit.","x-length-unit":"utf16_code_units"},"categories":{"type":"array","minItems":1,"maxItems":11,"uniqueItems":true,"items":{"type":"string","enum":["application","api","database","infrastructure","configuration","test","specification","documentation","project_kit","security","other"]}},"affectedObjects":{"type":"array","maxItems":2000,"items":{"type":"object","required":["stateKind","sourceScopeKey","objectKey","changeType","role","confidence"],"properties":{"stateKind":{"type":"string","enum":["infrastructure","data_model","data_flow"]},"sourceScopeKey":{"type":"string","pattern":"^(?:project|repository):[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$"},"objectKey":{"type":"string","minLength":1,"maxLength":1000},"changeType":{"type":"string","enum":["added","modified","removed","affected"]},"role":{"type":"string","enum":["primary","dependency","related"]},"confidence":{"type":"number","minimum":0,"maximum":1}},"additionalProperties":false}},"classificationSource":{"type":"string","enum":["deterministic","agent_enriched","mixed"]},"existingObjectResolution":{"const":"stable_identity_first"}},"additionalProperties":false},"evidenceProfile":{"type":"object","required":["contractId","version","requested","reported"],"properties":{"contractId":{"const":"cleartrace-delivery-evidence-profile-v1"},"version":{"const":1},"requested":{"type":"object","properties":{"change_detail":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"system_architecture":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"cloud_and_deployment":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"data_model":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"data_flow":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"tests":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"specifications":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]}},"additionalProperties":false},"reported":{"type":"object","properties":{"change_detail":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"system_architecture":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"cloud_and_deployment":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"data_model":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"data_flow":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"tests":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"specifications":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]}},"additionalProperties":false}},"additionalProperties":false},"evidenceRuntime":{"type":"object","required":["contractId","version","sourceMode","localGitAvailable","exactDiffAvailable","changeBasis","downgrades"],"properties":{"contractId":{"const":"cleartrace-evidence-runtime-v1"},"version":{"const":1},"sourceMode":{"type":"string","enum":["git","filesystem"]},"localGitAvailable":{"type":"boolean"},"exactDiffAvailable":{"type":"boolean"},"workingTreeScope":{"type":"object","additionalProperties":false,"required":["mode","selectedFiles"],"properties":{"mode":{"enum":["committed_only","selected_files","all_eligible_files"]},"selectedFiles":{"type":"array","uniqueItems":true,"items":{"type":"string","minLength":1}}}},"changeBasis":{"type":"string","enum":["git_working_tree","git_commit_range","filesystem_reported_paths","filesystem_current_state"]},"downgrades":{"type":"array","items":{"type":"object","required":["domain","requested","effective","reason"],"properties":{"domain":{"type":"string","enum":["change_detail","system_architecture","cloud_and_deployment","data_model","data_flow","tests","specifications"]},"requested":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"effective":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"reason":{"type":"string","enum":["local_git_required_for_exact_diff","available_evidence_below_requested_level"]}},"additionalProperties":false}}},"additionalProperties":false},"privacyMode":{"type":"string","enum":["reference_only","metadata_summary","snapshot_text","artifact_file"]},"patchText":{"type":"string","minLength":1,"description":"Git unified diff retained only when the approved privacy mode and evidence profile allow exact change detail."}},"additionalProperties":true},"links":{"type":"array","items":{"type":"object"}}},"additionalProperties":true}},"writeSet":{"anyOf":[{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://api.cleartrace.dev/ai-integration/v1/schemas/push-write-set.schema.json","title":"ClearTrace Push Write Set","description":"One coherent, authenticated group of related typed projection writes reviewed under a single approval hash.","type":"object","required":["contractId","writes"],"properties":{"contractId":{"const":"cleartrace-push-write-set-v1"},"writes":{"type":"array","minItems":1,"maxItems":20,"items":{"type":"object","required":["envelope"],"properties":{"envelope":{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://api.cleartrace.dev/ai-integration/v1/schemas/push-envelope.schema.json","title":"ClearTrace Push Envelope","type":"object","required":["contractId","pushType","sourceProjectId","solutionId","objectId","createdAt","payload"],"properties":{"contractId":{"type":"string"},"pushType":{"type":"string","enum":["test_run","finding","ticket","change_capsule"]},"sourceProjectId":{"type":"string"},"solutionId":{"type":"string"},"environmentId":{"type":["string","null"]},"objectId":{"type":"string"},"createdAt":{"type":"string","format":"date-time"},"sourceRefs":{"type":"array","items":{"type":"string"}},"evidenceRefs":{"type":"array","items":{"type":"string"}},"payload":{"type":"object"}},"additionalProperties":true},"projectionIntent":{"type":"string","enum":["current","historical"],"default":"current","description":"Use current for ordinary create/update work. Historical is explicit and currently supported only for an older ticket revision."}},"additionalProperties":false}}},"additionalProperties":false},{"type":"null"}]},"operationRuns":{"type":"array","maxItems":50,"description":"Runs of operations done in this task (deploy, migrate, clone, rotate, backup, restore...). Covered by the closeout planHash; identical retries store nothing twice. Release deployments stay in the release ledger.","items":{"type":"object","required":["kind","target","runs","startedAt","outcome","ranBy"],"additionalProperties":false,"properties":{"operation":{"anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}],"description":"Declared operation name from architecture/cleartrace-operations.json, or null."},"kind":{"type":"string","enum":["provision","deploy","migrate","rotate","backup","restore","clone","seed","check","other"]},"target":{"type":"string","pattern":"^[A-Za-z0-9][A-Za-z0-9._-]{0,63}:[A-Za-z0-9][A-Za-z0-9._-]{0,63}(:[A-Za-z0-9][A-Za-z0-9._-]{0,63})?$","description":"<environment>:<service>[:<database>]"},"runs":{"type":"string","minLength":1,"maxLength":500,"description":"Repository-relative script, workflow or runbook path."},"startedAt":{"type":"string","format":"date-time"},"finishedAt":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}]},"outcome":{"type":"string","enum":["succeeded","failed","partial","cancelled"]},"ranBy":{"type":"string","enum":["agent","user","ci"]},"actor":{"anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}],"description":"Name, handle or tool; never an email."},"evidenceRefs":{"type":"array","maxItems":20,"items":{"type":"string","minLength":1,"maxLength":500}},"notes":{"anyOf":[{"type":"string","maxLength":2000},{"type":"null"}],"description":"No secrets, keys, connection strings or local paths."},"projectId":{"anyOf":[{"type":"string","minLength":1,"maxLength":200},{"type":"null"}],"description":"Required only when the closeout has packages from several projects."}}}},"guard":{"type":"object","required":["writeSetCatalogFingerprint"],"properties":{"writeSetCatalogFingerprint":{"type":["string","null"],"pattern":"^sha256:[a-f0-9]{64}$"}},"additionalProperties":false}},"additionalProperties":false},"planHash":{"type":"string","pattern":"^sha256:[a-f0-9]{64}$"},"approved":{"const":true}},"additionalProperties":false},"ClearTracePackage":{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://api.cleartrace.dev/ai-integration/v1/schemas/changehub-package.schema.json","title":"ClearTrace Package","type":"object","required":["contractId","packageId","packageType","version","createdAt","scope","actor","source","contents"],"properties":{"contractId":{"type":"string","const":"changehub-package-v1"},"packageId":{"type":"string"},"packageType":{"type":"string"},"version":{"type":"integer","minimum":1},"createdAt":{"type":"string","format":"date-time"},"scope":{"type":"object"},"actor":{"type":"object"},"source":{"type":"object"},"contents":{"type":"object","properties":{"change":{"type":"object","required":["contractId","version","summary","categories","affectedObjects","classificationSource","existingObjectResolution"],"properties":{"contractId":{"const":"cleartrace-change-evidence-v1"},"version":{"const":1},"summary":{"type":"string","minLength":1,"maxLength":4000,"description":"Concise overview, 1–4000 trimmed UTF-16 code units; detailed analysis belongs in evidence. This is not a code/diff size limit.","x-length-unit":"utf16_code_units"},"categories":{"type":"array","minItems":1,"maxItems":11,"uniqueItems":true,"items":{"type":"string","enum":["application","api","database","infrastructure","configuration","test","specification","documentation","project_kit","security","other"]}},"affectedObjects":{"type":"array","maxItems":2000,"items":{"type":"object","required":["stateKind","sourceScopeKey","objectKey","changeType","role","confidence"],"properties":{"stateKind":{"type":"string","enum":["infrastructure","data_model","data_flow"]},"sourceScopeKey":{"type":"string","pattern":"^(?:project|repository):[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$"},"objectKey":{"type":"string","minLength":1,"maxLength":1000},"changeType":{"type":"string","enum":["added","modified","removed","affected"]},"role":{"type":"string","enum":["primary","dependency","related"]},"confidence":{"type":"number","minimum":0,"maximum":1}},"additionalProperties":false}},"classificationSource":{"type":"string","enum":["deterministic","agent_enriched","mixed"]},"existingObjectResolution":{"const":"stable_identity_first"}},"additionalProperties":false},"evidenceProfile":{"type":"object","required":["contractId","version","requested","reported"],"properties":{"contractId":{"const":"cleartrace-delivery-evidence-profile-v1"},"version":{"const":1},"requested":{"type":"object","properties":{"change_detail":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"system_architecture":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"cloud_and_deployment":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"data_model":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"data_flow":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"tests":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"specifications":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]}},"additionalProperties":false},"reported":{"type":"object","properties":{"change_detail":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"system_architecture":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"cloud_and_deployment":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"data_model":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"data_flow":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"tests":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"specifications":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]}},"additionalProperties":false}},"additionalProperties":false},"evidenceRuntime":{"type":"object","required":["contractId","version","sourceMode","localGitAvailable","exactDiffAvailable","changeBasis","downgrades"],"properties":{"contractId":{"const":"cleartrace-evidence-runtime-v1"},"version":{"const":1},"sourceMode":{"type":"string","enum":["git","filesystem"]},"localGitAvailable":{"type":"boolean"},"exactDiffAvailable":{"type":"boolean"},"workingTreeScope":{"type":"object","additionalProperties":false,"required":["mode","selectedFiles"],"properties":{"mode":{"enum":["committed_only","selected_files","all_eligible_files"]},"selectedFiles":{"type":"array","uniqueItems":true,"items":{"type":"string","minLength":1}}}},"changeBasis":{"type":"string","enum":["git_working_tree","git_commit_range","filesystem_reported_paths","filesystem_current_state"]},"downgrades":{"type":"array","items":{"type":"object","required":["domain","requested","effective","reason"],"properties":{"domain":{"type":"string","enum":["change_detail","system_architecture","cloud_and_deployment","data_model","data_flow","tests","specifications"]},"requested":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"effective":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"reason":{"type":"string","enum":["local_git_required_for_exact_diff","available_evidence_below_requested_level"]}},"additionalProperties":false}}},"additionalProperties":false},"privacyMode":{"type":"string","enum":["reference_only","metadata_summary","snapshot_text","artifact_file"]},"patchText":{"type":"string","minLength":1,"description":"Git unified diff retained only when the approved privacy mode and evidence profile allow exact change detail."}},"additionalProperties":true},"links":{"type":"array","items":{"type":"object"}}},"additionalProperties":true},"WorkspaceDiscoveryRequest":{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://api.cleartrace.dev/ai-integration/v1/schemas/workspace-discovery.schema.json","title":"ClearTrace Workspace Discovery Request","description":"Metadata-only local workspace inventory used to preview solution/project adoption and controlled metadata synchronization. Existing matches expose field-level changes for allowed mutable fields. Raw contents, local paths, and credentials are rejected.","type":"object","required":["contractId","discoveryId","revision","solutions"],"properties":{"contractId":{"const":"cleartrace-workspace-discovery-v1"},"discoveryId":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$"},"revision":{"const":1},"solutions":{"type":"array","minItems":1,"maxItems":50,"items":{"type":"object","required":["candidateId","name","projects"],"properties":{"candidateId":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$"},"name":{"type":"string","minLength":1,"maxLength":120},"summary":{"type":"string","maxLength":400},"installedSolutionId":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$"},"discoveryFingerprint":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:+/=-]{0,255}$"},"projects":{"type":"array","minItems":1,"maxItems":200,"items":{"type":"object","required":["candidateId","name","projectType","methodologyMode","isOrchestrationProject"],"properties":{"candidateId":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$"},"name":{"type":"string","minLength":1,"maxLength":120},"summary":{"type":"string","maxLength":400},"projectType":{"type":"string","minLength":1,"maxLength":64},"methodologyMode":{"type":"string","enum":["acdc","inferred","custom"]},"isOrchestrationProject":{"type":"boolean"},"installedProjectId":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$"},"discoveryFingerprint":{"type":"string","minLength":1,"maxLength":256,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:+/=-]{0,255}$"},"repository":{"type":"object","required":["remoteUrl"],"properties":{"remoteUrl":{"type":"string","minLength":1,"maxLength":500},"defaultBranch":{"type":"string","minLength":1,"maxLength":120},"installedRepositoryId":{"type":"string","minLength":1,"maxLength":160,"pattern":"^[A-Za-z0-9][A-Za-z0-9._:-]{0,159}$"}},"additionalProperties":false}},"additionalProperties":false}}},"additionalProperties":false}}},"additionalProperties":false},"WorkspaceDiscoveryApplyRequest":{"type":"object","required":["discovery","planHash","approved"],"properties":{"discovery":{"$ref":"#/components/schemas/WorkspaceDiscoveryRequest"},"planHash":{"type":"string","minLength":1,"maxLength":160},"selectedOperationIds":{"type":"array","maxItems":250,"uniqueItems":true,"items":{"type":"string","minLength":1,"maxLength":160}},"approved":{"const":true}},"additionalProperties":false},"ProjectKit":{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://api.cleartrace.dev/ai-integration/v1/schemas/project-kit.schema.json","title":"ClearTrace Project Kit","description":"Install-ready project identity and scanner integration configuration. Repository and tenant bindings are required.","type":"object","required":["$schema","kitVersion","schemaVersion","minimumScannerVersion","updatePolicy","release","projectKitId","tenantId","solutionId","solutionName","projectId","projectName","projectFunction","repositoryId","isOrchestrationProject","repository","privacyMode","privacy","evidencePolicy","integration","foundationRefs","componentManifestEndpoint","contracts"],"properties":{"$schema":{"const":"https://api.cleartrace.dev/ai-integration/v1/schemas/project-kit.schema.json"},"kitVersion":{"type":"string","pattern":"^[0-9]+\\.[0-9]+\\.[0-9]+(?:[-+][A-Za-z0-9.-]+)?$"},"schemaVersion":{"type":"integer","minimum":1},"minimumScannerVersion":{"type":"string","pattern":"^[0-9]+\\.[0-9]+\\.[0-9]+(?:[-+][A-Za-z0-9.-]+)?$"},"updatePolicy":{"const":"preview_apply"},"release":{"type":"object","required":["kitVersion","schemaVersion","minimumScannerVersion","immutable","updatePolicy"],"properties":{"kitVersion":{"type":"string","pattern":"^[0-9]+\\.[0-9]+\\.[0-9]+(?:[-+][A-Za-z0-9.-]+)?$"},"schemaVersion":{"type":"integer","minimum":1},"minimumScannerVersion":{"type":"string","pattern":"^[0-9]+\\.[0-9]+\\.[0-9]+(?:[-+][A-Za-z0-9.-]+)?$"},"immutable":{"const":true},"updatePolicy":{"const":"preview_apply"}},"additionalProperties":false},"projectKitId":{"type":"string","minLength":1,"maxLength":256},"tenantId":{"type":"string","minLength":1,"maxLength":256},"solutionId":{"type":"string","minLength":1,"maxLength":256},"solutionName":{"type":"string","minLength":1,"maxLength":500},"projectId":{"type":"string","minLength":1,"maxLength":256},"projectName":{"type":"string","minLength":1,"maxLength":500},"projectFunction":{"type":"string","minLength":1,"maxLength":256},"repositoryId":{"anyOf":[{"type":"string","minLength":1,"maxLength":256},{"type":"null"}]},"isOrchestrationProject":{"type":"boolean"},"repository":{"type":"object","required":["repositoryId","url","defaultBranch","mode"],"properties":{"repositoryId":{"anyOf":[{"type":"string","minLength":1,"maxLength":256},{"type":"null"}]},"url":{"anyOf":[{"type":"null"},{"type":"string","minLength":1,"maxLength":1000,"anyOf":[{"pattern":"^https://(?![^/]*@)[^\\s?#]+$"},{"pattern":"^ssh://(?:[A-Za-z0-9._-]+@)?[^\\s/?#]+/[^\\s?#]+$"},{"pattern":"^git://[^\\s/?#]+/[^\\s?#]+$"},{"pattern":"^(?:[A-Za-z0-9._-]+@)?[A-Za-z0-9.-]+:[^/\\s?#][^\\s?#]*$"}]}]},"defaultBranch":{"type":["string","null"],"minLength":1,"maxLength":256},"mode":{"type":"string","minLength":1,"maxLength":64}},"additionalProperties":false},"privacyMode":{"type":"string","enum":["reference_only","metadata_summary","snapshot_text","artifact_file"]},"privacy":{"type":"object","required":["mode","allowPatchText","allowRawSourceUpload"],"properties":{"mode":{"type":"string","enum":["reference_only","metadata_summary","snapshot_text","artifact_file"]},"allowPatchText":{"type":"boolean"},"allowRawSourceUpload":{"const":false}},"additionalProperties":false},"evidencePolicy":{"type":"object","required":["version","defaultLevel","domainOverrides"],"properties":{"version":{"const":1},"defaultLevel":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"domainOverrides":{"type":"object","properties":{"change_detail":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"system_architecture":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"cloud_and_deployment":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"data_model":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"data_flow":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"tests":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"specifications":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]}},"additionalProperties":false}},"additionalProperties":false},"integration":{"type":"object","required":["apiBaseUrl","mcpEndpoint","basePath","discovery","docs","openapi","capabilities","assistantGuide","agentSpec","developerGuide","kitLatest","kitReleases","packageLint","packageSubmitEndpoint","packageValidateEndpoint","workspaceDiscoveryPreviewEndpoint","workspaceDiscoveryApplyEndpoint","ticketValidateEndpoint","changeCapsuleValidateEndpoint","pushWriteSetPreviewEndpoint","pushWriteSetSubmitEndpoint","workingPlanResolutionEndpoint","workingPlansEndpoint","createWorkingPlanEndpoint","updateWorkingPlanEndpoint","appendWorkingPlanEventEndpoint","ticketSchema","changeCapsuleSchema","pushWriteSetSchema","searchEndpoint","ticketsEndpoint","changeCapsulesEndpoint","projectAgentSpecEndpoint","projectContextEndpoint","projectChangeStateEndpoint","apiKeyEnv"],"properties":{"apiBaseUrl":{"type":"string","minLength":1,"maxLength":1000,"pattern":"^https?://"},"mcpEndpoint":{"type":"string","minLength":1,"maxLength":1000,"pattern":"^https?://"},"basePath":{"const":"/ai-integration/v1"},"discovery":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"docs":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"openapi":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"capabilities":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"assistantGuide":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"agentSpec":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"developerGuide":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"kitLatest":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"kitReleases":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"packageLint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"packageSubmitEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"packageValidateEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"workspaceDiscoveryPreviewEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"workspaceDiscoveryApplyEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"ticketValidateEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"changeCapsuleValidateEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"pushWriteSetPreviewEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"pushWriteSetSubmitEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"workingPlanResolutionEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"workingPlansEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"createWorkingPlanEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"updateWorkingPlanEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"appendWorkingPlanEventEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"ticketSchema":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"changeCapsuleSchema":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"pushWriteSetSchema":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"searchEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"ticketsEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"changeCapsulesEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"projectAgentSpecEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"projectContextEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"projectChangeStateEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"apiKeyEnv":{"const":"CLEARTRACE_API_KEY"}},"additionalProperties":false},"foundationRefs":{"type":"object","required":["clearTraceHelp","evolutionPolicy","foundationSpecs"],"properties":{"clearTraceHelp":{"type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":1000}},"evolutionPolicy":{"type":"object","required":["contractId","version","updateExistingBeforeCreate","managedBundleWriteRule","triggerKinds","resolutionOrder","newSpecRegistration","evidenceRule"],"properties":{"contractId":{"const":"cleartrace-foundation-evolution-v1"},"version":{"const":1},"updateExistingBeforeCreate":{"const":true},"managedBundleWriteRule":{"type":"string","minLength":1,"maxLength":4000},"triggerKinds":{"type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":1000}},"resolutionOrder":{"type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":1000}},"newSpecRegistration":{"type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":1000}},"evidenceRule":{"type":"string","minLength":1,"maxLength":4000}},"additionalProperties":false},"foundationSpecs":{"type":"array","maxItems":500,"items":{"type":"object","required":["foundationSpecId","title","specType","pathOrUri","appliesTo","privacyMode","supportedLocales"],"properties":{"foundationSpecId":{"type":"string","minLength":1,"maxLength":256},"title":{"type":"string","minLength":1,"maxLength":500},"specType":{"type":"string","minLength":1,"maxLength":100},"pathOrUri":{"type":"string","minLength":1,"maxLength":512},"appliesTo":{"type":"string","enum":["cleartrace_product","tracked_project","both"]},"privacyMode":{"type":"string","enum":["reference_only","metadata_summary","snapshot_text","artifact_file"]},"supportedLocales":{"type":"array","maxItems":50,"items":{"type":"string","minLength":1,"maxLength":1000}}},"additionalProperties":false}}},"additionalProperties":false},"componentManifestEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"contracts":{"type":"array","maxItems":50,"items":{"type":"string","minLength":1,"maxLength":1000},"contains":{"const":"changehub-package-v1"},"minContains":1}},"additionalProperties":false},"ProjectKitReleaseArtifact":{"type":"object","required":["kitVersion","schemaVersion","minimumScannerVersion","immutable","updatePolicy"],"properties":{"kitVersion":{"type":"string","pattern":"^[0-9]+\\.[0-9]+\\.[0-9]+(?:[-+][A-Za-z0-9.-]+)?$"},"schemaVersion":{"type":"integer","minimum":1},"minimumScannerVersion":{"type":"string","pattern":"^[0-9]+\\.[0-9]+\\.[0-9]+(?:[-+][A-Za-z0-9.-]+)?$"},"immutable":{"const":true},"updatePolicy":{"const":"preview_apply"}},"additionalProperties":false},"ProjectKitRelease":{"type":"object","required":["kitVersion","schemaVersion","minimumScannerVersion","lifecycleStatus","supported","current","immutable","updatePolicy"],"properties":{"kitVersion":{"type":"string","pattern":"^[0-9]+\\.[0-9]+\\.[0-9]+(?:[-+][A-Za-z0-9.-]+)?$"},"schemaVersion":{"type":"integer","minimum":1},"minimumScannerVersion":{"type":"string","pattern":"^[0-9]+\\.[0-9]+\\.[0-9]+(?:[-+][A-Za-z0-9.-]+)?$"},"lifecycleStatus":{"type":"string","enum":["published","deprecated","unsupported"]},"supported":{"type":"boolean"},"current":{"type":"boolean"},"immutable":{"const":true},"updatePolicy":{"const":"preview_apply"}},"additionalProperties":false},"ProjectKitReleaseRegistryResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["contractId","currentKitVersion","updatePolicy","releases","rules"],"properties":{"contractId":{"const":"cleartrace-project-kit-release-registry-v1"},"currentKitVersion":{"type":"string"},"updatePolicy":{"const":"preview_apply"},"releases":{"type":"array","minItems":1,"items":{"$ref":"#/components/schemas/ProjectKitRelease"}},"rules":{"type":"object","required":["immutableCompatibilityContracts","mutableLifecyclePolicy","automaticBehavior","applyBehavior","breakingUpdates"],"properties":{"immutableCompatibilityContracts":{"const":true},"mutableLifecyclePolicy":{"const":true},"automaticBehavior":{"type":"string","minLength":1},"applyBehavior":{"type":"string","minLength":1},"breakingUpdates":{"type":"string","minLength":1}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false},"ProjectKitLifecycleState":{"type":"object","required":["currentRelease","schemaVersion","minimumScannerVersion","currentBundleHash","installedProjectKitId","installedKitVersion","installedScannerVersion","installedBundleHash","installedAt","behaviorInstallationStatus","updateStatus","updateReason","recommendedAction"],"properties":{"currentRelease":{"$ref":"#/components/schemas/ProjectKitRelease"},"schemaVersion":{"type":"integer","minimum":1},"minimumScannerVersion":{"type":"string","pattern":"^[0-9]+\\.[0-9]+\\.[0-9]+(?:[-+][A-Za-z0-9.-]+)?$"},"currentBundleHash":{"type":["string","null"],"pattern":"^sha256:[a-f0-9]{64}$"},"installedProjectKitId":{"type":["string","null"]},"installedKitVersion":{"type":["string","null"]},"installedScannerVersion":{"type":["string","null"]},"installedBundleHash":{"type":["string","null"],"pattern":"^sha256:[a-f0-9]{64}$"},"installedAt":{"type":["string","null"],"format":"date-time"},"behaviorInstallationStatus":{"type":"string","enum":["not_reported","kit_only","verified","update_required"]},"updateStatus":{"type":"string","enum":["not_reported","current","update_available","update_required"]},"updateReason":{"type":["string","null"],"enum":["kit_version_behind","bundle_drift","bundle_hash_missing","bundle_verification_unavailable","scanner_incompatible","kit_identity_mismatch","installed_version_unsupported","installed_version_ahead","assistant_adapter_unverified",null]},"recommendedAction":{"type":["string","null"],"enum":["upgrade_kit","refresh_bundle","publish_evidence","update_scanner","restore_project_readiness","recover_installation","manual_recovery","verify_installation",null]}},"additionalProperties":false},"ProjectKitReadiness":{"type":"object","required":["status","installReady","blockers"],"properties":{"status":{"type":"string","enum":["ready_to_install","needs_tenant_binding","needs_repository_binding","needs_supported_kit"]},"installReady":{"type":"boolean"},"blockers":{"type":"array","uniqueItems":true,"items":{"type":"string","minLength":1}},"selectedKitVersion":{"type":["string","null"]},"selectedKitStatus":{"type":["string","null"]}},"additionalProperties":false},"ProjectKitLifecycleSummary":{"type":"object","required":["tenantId","solutionId","solutionName","projectId","projectName","projectFunction","projectStatus","connectionMode","isOrchestrationProject","repositoryUrl","projectKitId","kitStatus","kitVersion","currentRelease","schemaVersion","minimumScannerVersion","currentBundleHash","installedProjectKitId","installedKitVersion","installedScannerVersion","installedBundleHash","installedAt","behaviorInstallationStatus","updateStatus","updateReason","recommendedAction","lifecycleStatus","installReady","readiness","links"],"properties":{"tenantId":{"type":["string","null"]},"solutionId":{"type":"string","minLength":1},"solutionName":{"type":["string","null"]},"projectId":{"type":"string","minLength":1},"projectName":{"type":"string","minLength":1},"projectFunction":{"type":"string","minLength":1},"projectStatus":{"type":"string","enum":["active","archived"]},"connectionMode":{"type":["string","null"],"enum":["local_scanner","external_producer","catalog_only",null]},"isOrchestrationProject":{"type":"boolean"},"repositoryUrl":{"type":["string","null"]},"projectKitId":{"type":"string","minLength":1},"kitStatus":{"type":"string","enum":["draft","published","deprecated"]},"kitVersion":{"type":"string","pattern":"^(?:v0|0|[0-9]+\\.[0-9]+\\.[0-9]+(?:[-+][A-Za-z0-9.-]+)?)$"},"currentRelease":{"$ref":"#/components/schemas/ProjectKitRelease"},"schemaVersion":{"type":"integer","minimum":1},"minimumScannerVersion":{"type":"string","pattern":"^[0-9]+\\.[0-9]+\\.[0-9]+(?:[-+][A-Za-z0-9.-]+)?$"},"currentBundleHash":{"type":["string","null"],"pattern":"^sha256:[a-f0-9]{64}$"},"installedProjectKitId":{"type":["string","null"]},"installedKitVersion":{"type":["string","null"]},"installedScannerVersion":{"type":["string","null"]},"installedBundleHash":{"type":["string","null"],"pattern":"^sha256:[a-f0-9]{64}$"},"installedAt":{"type":["string","null"],"format":"date-time"},"behaviorInstallationStatus":{"type":"string","enum":["not_reported","kit_only","verified","update_required"]},"updateStatus":{"type":"string","enum":["not_reported","current","update_available","update_required"]},"updateReason":{"type":["string","null"],"enum":["kit_version_behind","bundle_drift","bundle_hash_missing","bundle_verification_unavailable","scanner_incompatible","kit_identity_mismatch","installed_version_unsupported","installed_version_ahead","assistant_adapter_unverified",null]},"recommendedAction":{"type":["string","null"],"enum":["upgrade_kit","refresh_bundle","publish_evidence","update_scanner","restore_project_readiness","recover_installation","manual_recovery","verify_installation",null]},"lifecycleStatus":{"type":"string","enum":["ready_to_install","needs_tenant_binding","needs_repository_binding","needs_supported_kit"]},"installReady":{"type":"boolean"},"readiness":{"$ref":"#/components/schemas/ProjectKitReadiness"},"links":{"type":"object","required":["detail","download","scannerConfig","foundation","agentSpec","context","changeState","tickets","changeCapsules","workingPlanResolution","workingPlans","components","componentManifests"],"properties":{"detail":{"type":"string","minLength":1},"download":{"type":"string","minLength":1},"scannerConfig":{"type":"string","minLength":1},"foundation":{"type":"string","minLength":1},"agentSpec":{"type":"string","minLength":1},"context":{"type":"string","minLength":1},"changeState":{"type":"string","minLength":1},"tickets":{"type":"string","minLength":1},"changeCapsules":{"type":"string","minLength":1},"workingPlanResolution":{"type":"string","minLength":1},"workingPlans":{"type":"string","minLength":1},"components":{"type":"string","minLength":1},"componentManifests":{"type":"string","minLength":1}},"additionalProperties":false}},"additionalProperties":false},"ProjectKitLifecycleDetail":{"type":"object","required":["summary","currentRelease","schemaVersion","minimumScannerVersion","currentBundleHash","installedProjectKitId","installedKitVersion","installedScannerVersion","installedBundleHash","installedAt","behaviorInstallationStatus","updateStatus","updateReason","recommendedAction","kit","config","scannerConfig","agentSpec","foundation","componentManifests","procedure"],"properties":{"summary":{"$ref":"#/components/schemas/ProjectKitLifecycleSummary"},"currentRelease":{"$ref":"#/components/schemas/ProjectKitRelease"},"schemaVersion":{"type":"integer","minimum":1},"minimumScannerVersion":{"type":"string","pattern":"^[0-9]+\\.[0-9]+\\.[0-9]+(?:[-+][A-Za-z0-9.-]+)?$"},"currentBundleHash":{"type":["string","null"],"pattern":"^sha256:[a-f0-9]{64}$"},"installedProjectKitId":{"type":["string","null"]},"installedKitVersion":{"type":["string","null"]},"installedScannerVersion":{"type":["string","null"]},"installedBundleHash":{"type":["string","null"],"pattern":"^sha256:[a-f0-9]{64}$"},"installedAt":{"type":["string","null"],"format":"date-time"},"behaviorInstallationStatus":{"type":"string","enum":["not_reported","kit_only","verified","update_required"]},"updateStatus":{"type":"string","enum":["not_reported","current","update_available","update_required"]},"updateReason":{"type":["string","null"],"enum":["kit_version_behind","bundle_drift","bundle_hash_missing","bundle_verification_unavailable","scanner_incompatible","kit_identity_mismatch","installed_version_unsupported","installed_version_ahead","assistant_adapter_unverified",null]},"recommendedAction":{"type":["string","null"],"enum":["upgrade_kit","refresh_bundle","publish_evidence","update_scanner","restore_project_readiness","recover_installation","manual_recovery","verify_installation",null]},"kit":{"type":["object","null"],"additionalProperties":true},"config":{"type":["object","null"],"additionalProperties":true},"scannerConfig":{"type":["object","null"],"additionalProperties":true},"agentSpec":{"type":"object","additionalProperties":true},"foundation":{"type":"object","additionalProperties":true},"componentManifests":{"type":"array","items":{"type":"object","additionalProperties":true}},"procedure":{"type":"array","items":{"type":"string","minLength":1}}},"additionalProperties":false},"ProjectKitLifecycleListResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ProjectKitLifecycleSummary"}}},"additionalProperties":false},"ProjectKitLifecycleDetailResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ProjectKitLifecycleDetail"}},"additionalProperties":false},"ProjectKitBundle":{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://api.cleartrace.dev/ai-integration/v1/schemas/project-kit-bundle.schema.json","title":"ClearTrace Project Kit Bundle","description":"Versioned, integrity-addressed distribution bundle containing exactly the five installable .cleartrace JSON files. Content is project-bound, Git provenance is optional, raw-source upload is disabled, and local writes require a separate preview/apply installer approval.","type":"object","required":["$schema","contractId","version","fileName","contentType","content","files","install","bundleHash"],"properties":{"$schema":{"const":"https://api.cleartrace.dev/ai-integration/v1/schemas/project-kit-bundle.schema.json"},"contractId":{"const":"cleartrace-project-kit-bundle-v1"},"version":{"const":1},"fileName":{"const":".cleartrace/project-kit.json"},"contentType":{"const":"application/json"},"content":{"type":"object","required":["$schema","kitVersion","schemaVersion","minimumScannerVersion","updatePolicy","release","projectKitId","tenantId","solutionId","solutionName","projectId","projectName","projectFunction","repositoryId","isOrchestrationProject","repository","privacyMode","privacy","evidencePolicy","integration","foundationRefs","componentManifestEndpoint","contracts"],"properties":{"$schema":{"const":"https://api.cleartrace.dev/ai-integration/v1/schemas/project-kit.schema.json"},"kitVersion":{"type":"string","pattern":"^[0-9]+\\.[0-9]+\\.[0-9]+(?:[-+][A-Za-z0-9.-]+)?$"},"schemaVersion":{"type":"integer","minimum":1},"minimumScannerVersion":{"type":"string","pattern":"^[0-9]+\\.[0-9]+\\.[0-9]+(?:[-+][A-Za-z0-9.-]+)?$"},"updatePolicy":{"const":"preview_apply"},"release":{"type":"object","required":["kitVersion","schemaVersion","minimumScannerVersion","immutable","updatePolicy"],"properties":{"kitVersion":{"type":"string","pattern":"^[0-9]+\\.[0-9]+\\.[0-9]+(?:[-+][A-Za-z0-9.-]+)?$"},"schemaVersion":{"type":"integer","minimum":1},"minimumScannerVersion":{"type":"string","pattern":"^[0-9]+\\.[0-9]+\\.[0-9]+(?:[-+][A-Za-z0-9.-]+)?$"},"immutable":{"const":true},"updatePolicy":{"const":"preview_apply"}},"additionalProperties":false},"projectKitId":{"type":"string","minLength":1,"maxLength":256},"tenantId":{"type":"string","minLength":1,"maxLength":256},"solutionId":{"type":"string","minLength":1,"maxLength":256},"solutionName":{"type":"string","minLength":1,"maxLength":500},"projectId":{"type":"string","minLength":1,"maxLength":256},"projectName":{"type":"string","minLength":1,"maxLength":500},"projectFunction":{"type":"string","minLength":1,"maxLength":256},"repositoryId":{"anyOf":[{"type":"string","minLength":1,"maxLength":256},{"type":"null"}]},"isOrchestrationProject":{"type":"boolean"},"repository":{"type":"object","required":["repositoryId","url","defaultBranch","mode"],"properties":{"repositoryId":{"anyOf":[{"type":"string","minLength":1,"maxLength":256},{"type":"null"}]},"url":{"anyOf":[{"type":"null"},{"type":"string","minLength":1,"maxLength":1000,"anyOf":[{"pattern":"^https://(?![^/]*@)[^\\s?#]+$"},{"pattern":"^ssh://(?:[A-Za-z0-9._-]+@)?[^\\s/?#]+/[^\\s?#]+$"},{"pattern":"^git://[^\\s/?#]+/[^\\s?#]+$"},{"pattern":"^(?:[A-Za-z0-9._-]+@)?[A-Za-z0-9.-]+:[^/\\s?#][^\\s?#]*$"}]}]},"defaultBranch":{"type":["string","null"],"minLength":1,"maxLength":256},"mode":{"type":"string","minLength":1,"maxLength":64}},"additionalProperties":false},"privacyMode":{"type":"string","enum":["reference_only","metadata_summary","snapshot_text","artifact_file"]},"privacy":{"type":"object","required":["mode","allowPatchText","allowRawSourceUpload"],"properties":{"mode":{"type":"string","enum":["reference_only","metadata_summary","snapshot_text","artifact_file"]},"allowPatchText":{"type":"boolean"},"allowRawSourceUpload":{"const":false}},"additionalProperties":false},"evidencePolicy":{"type":"object","required":["version","defaultLevel","domainOverrides"],"properties":{"version":{"const":1},"defaultLevel":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"domainOverrides":{"type":"object","properties":{"change_detail":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"system_architecture":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"cloud_and_deployment":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"data_model":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"data_flow":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"tests":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"specifications":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]}},"additionalProperties":false}},"additionalProperties":false},"integration":{"type":"object","required":["apiBaseUrl","mcpEndpoint","basePath","discovery","docs","openapi","capabilities","assistantGuide","agentSpec","developerGuide","kitLatest","kitReleases","packageLint","packageSubmitEndpoint","packageValidateEndpoint","workspaceDiscoveryPreviewEndpoint","workspaceDiscoveryApplyEndpoint","ticketValidateEndpoint","changeCapsuleValidateEndpoint","pushWriteSetPreviewEndpoint","pushWriteSetSubmitEndpoint","workingPlanResolutionEndpoint","workingPlansEndpoint","createWorkingPlanEndpoint","updateWorkingPlanEndpoint","appendWorkingPlanEventEndpoint","ticketSchema","changeCapsuleSchema","pushWriteSetSchema","searchEndpoint","ticketsEndpoint","changeCapsulesEndpoint","projectAgentSpecEndpoint","projectContextEndpoint","projectChangeStateEndpoint","apiKeyEnv"],"properties":{"apiBaseUrl":{"type":"string","minLength":1,"maxLength":1000,"pattern":"^https?://"},"mcpEndpoint":{"type":"string","minLength":1,"maxLength":1000,"pattern":"^https?://"},"basePath":{"const":"/ai-integration/v1"},"discovery":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"docs":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"openapi":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"capabilities":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"assistantGuide":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"agentSpec":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"developerGuide":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"kitLatest":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"kitReleases":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"packageLint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"packageSubmitEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"packageValidateEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"workspaceDiscoveryPreviewEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"workspaceDiscoveryApplyEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"ticketValidateEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"changeCapsuleValidateEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"pushWriteSetPreviewEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"pushWriteSetSubmitEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"workingPlanResolutionEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"workingPlansEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"createWorkingPlanEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"updateWorkingPlanEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"appendWorkingPlanEventEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"ticketSchema":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"changeCapsuleSchema":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"pushWriteSetSchema":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"searchEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"ticketsEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"changeCapsulesEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"projectAgentSpecEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"projectContextEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"projectChangeStateEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"apiKeyEnv":{"const":"CLEARTRACE_API_KEY"}},"additionalProperties":false},"foundationRefs":{"type":"object","required":["clearTraceHelp","evolutionPolicy","foundationSpecs"],"properties":{"clearTraceHelp":{"type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":1000}},"evolutionPolicy":{"type":"object","required":["contractId","version","updateExistingBeforeCreate","managedBundleWriteRule","triggerKinds","resolutionOrder","newSpecRegistration","evidenceRule"],"properties":{"contractId":{"const":"cleartrace-foundation-evolution-v1"},"version":{"const":1},"updateExistingBeforeCreate":{"const":true},"managedBundleWriteRule":{"type":"string","minLength":1,"maxLength":4000},"triggerKinds":{"type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":1000}},"resolutionOrder":{"type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":1000}},"newSpecRegistration":{"type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":1000}},"evidenceRule":{"type":"string","minLength":1,"maxLength":4000}},"additionalProperties":false},"foundationSpecs":{"type":"array","maxItems":500,"items":{"type":"object","required":["foundationSpecId","title","specType","pathOrUri","appliesTo","privacyMode","supportedLocales"],"properties":{"foundationSpecId":{"type":"string","minLength":1,"maxLength":256},"title":{"type":"string","minLength":1,"maxLength":500},"specType":{"type":"string","minLength":1,"maxLength":100},"pathOrUri":{"type":"string","minLength":1,"maxLength":512},"appliesTo":{"type":"string","enum":["cleartrace_product","tracked_project","both"]},"privacyMode":{"type":"string","enum":["reference_only","metadata_summary","snapshot_text","artifact_file"]},"supportedLocales":{"type":"array","maxItems":50,"items":{"type":"string","minLength":1,"maxLength":1000}}},"additionalProperties":false}}},"additionalProperties":false},"componentManifestEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"contracts":{"type":"array","maxItems":50,"items":{"type":"string","minLength":1,"maxLength":1000},"contains":{"const":"changehub-package-v1"},"minContains":1}},"additionalProperties":false},"files":{"type":"array","minItems":5,"maxItems":5,"prefixItems":[{"type":"object","required":["fileName","contentType","sha256","content"],"properties":{"fileName":{"const":".cleartrace/project-kit.json"},"contentType":{"const":"application/json"},"sha256":{"type":"string","pattern":"^sha256:[a-f0-9]{64}$"},"content":{"type":"object","required":["$schema","kitVersion","schemaVersion","minimumScannerVersion","updatePolicy","release","projectKitId","tenantId","solutionId","solutionName","projectId","projectName","projectFunction","repositoryId","isOrchestrationProject","repository","privacyMode","privacy","evidencePolicy","integration","foundationRefs","componentManifestEndpoint","contracts"],"properties":{"$schema":{"const":"https://api.cleartrace.dev/ai-integration/v1/schemas/project-kit.schema.json"},"kitVersion":{"type":"string","pattern":"^[0-9]+\\.[0-9]+\\.[0-9]+(?:[-+][A-Za-z0-9.-]+)?$"},"schemaVersion":{"type":"integer","minimum":1},"minimumScannerVersion":{"type":"string","pattern":"^[0-9]+\\.[0-9]+\\.[0-9]+(?:[-+][A-Za-z0-9.-]+)?$"},"updatePolicy":{"const":"preview_apply"},"release":{"type":"object","required":["kitVersion","schemaVersion","minimumScannerVersion","immutable","updatePolicy"],"properties":{"kitVersion":{"type":"string","pattern":"^[0-9]+\\.[0-9]+\\.[0-9]+(?:[-+][A-Za-z0-9.-]+)?$"},"schemaVersion":{"type":"integer","minimum":1},"minimumScannerVersion":{"type":"string","pattern":"^[0-9]+\\.[0-9]+\\.[0-9]+(?:[-+][A-Za-z0-9.-]+)?$"},"immutable":{"const":true},"updatePolicy":{"const":"preview_apply"}},"additionalProperties":false},"projectKitId":{"type":"string","minLength":1,"maxLength":256},"tenantId":{"type":"string","minLength":1,"maxLength":256},"solutionId":{"type":"string","minLength":1,"maxLength":256},"solutionName":{"type":"string","minLength":1,"maxLength":500},"projectId":{"type":"string","minLength":1,"maxLength":256},"projectName":{"type":"string","minLength":1,"maxLength":500},"projectFunction":{"type":"string","minLength":1,"maxLength":256},"repositoryId":{"anyOf":[{"type":"string","minLength":1,"maxLength":256},{"type":"null"}]},"isOrchestrationProject":{"type":"boolean"},"repository":{"type":"object","required":["repositoryId","url","defaultBranch","mode"],"properties":{"repositoryId":{"anyOf":[{"type":"string","minLength":1,"maxLength":256},{"type":"null"}]},"url":{"anyOf":[{"type":"null"},{"type":"string","minLength":1,"maxLength":1000,"anyOf":[{"pattern":"^https://(?![^/]*@)[^\\s?#]+$"},{"pattern":"^ssh://(?:[A-Za-z0-9._-]+@)?[^\\s/?#]+/[^\\s?#]+$"},{"pattern":"^git://[^\\s/?#]+/[^\\s?#]+$"},{"pattern":"^(?:[A-Za-z0-9._-]+@)?[A-Za-z0-9.-]+:[^/\\s?#][^\\s?#]*$"}]}]},"defaultBranch":{"type":["string","null"],"minLength":1,"maxLength":256},"mode":{"type":"string","minLength":1,"maxLength":64}},"additionalProperties":false},"privacyMode":{"type":"string","enum":["reference_only","metadata_summary","snapshot_text","artifact_file"]},"privacy":{"type":"object","required":["mode","allowPatchText","allowRawSourceUpload"],"properties":{"mode":{"type":"string","enum":["reference_only","metadata_summary","snapshot_text","artifact_file"]},"allowPatchText":{"type":"boolean"},"allowRawSourceUpload":{"const":false}},"additionalProperties":false},"evidencePolicy":{"type":"object","required":["version","defaultLevel","domainOverrides"],"properties":{"version":{"const":1},"defaultLevel":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"domainOverrides":{"type":"object","properties":{"change_detail":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"system_architecture":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"cloud_and_deployment":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"data_model":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"data_flow":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"tests":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"specifications":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]}},"additionalProperties":false}},"additionalProperties":false},"integration":{"type":"object","required":["apiBaseUrl","mcpEndpoint","basePath","discovery","docs","openapi","capabilities","assistantGuide","agentSpec","developerGuide","kitLatest","kitReleases","packageLint","packageSubmitEndpoint","packageValidateEndpoint","workspaceDiscoveryPreviewEndpoint","workspaceDiscoveryApplyEndpoint","ticketValidateEndpoint","changeCapsuleValidateEndpoint","pushWriteSetPreviewEndpoint","pushWriteSetSubmitEndpoint","workingPlanResolutionEndpoint","workingPlansEndpoint","createWorkingPlanEndpoint","updateWorkingPlanEndpoint","appendWorkingPlanEventEndpoint","ticketSchema","changeCapsuleSchema","pushWriteSetSchema","searchEndpoint","ticketsEndpoint","changeCapsulesEndpoint","projectAgentSpecEndpoint","projectContextEndpoint","projectChangeStateEndpoint","apiKeyEnv"],"properties":{"apiBaseUrl":{"type":"string","minLength":1,"maxLength":1000,"pattern":"^https?://"},"mcpEndpoint":{"type":"string","minLength":1,"maxLength":1000,"pattern":"^https?://"},"basePath":{"const":"/ai-integration/v1"},"discovery":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"docs":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"openapi":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"capabilities":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"assistantGuide":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"agentSpec":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"developerGuide":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"kitLatest":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"kitReleases":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"packageLint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"packageSubmitEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"packageValidateEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"workspaceDiscoveryPreviewEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"workspaceDiscoveryApplyEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"ticketValidateEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"changeCapsuleValidateEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"pushWriteSetPreviewEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"pushWriteSetSubmitEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"workingPlanResolutionEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"workingPlansEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"createWorkingPlanEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"updateWorkingPlanEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"appendWorkingPlanEventEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"ticketSchema":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"changeCapsuleSchema":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"pushWriteSetSchema":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"searchEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"ticketsEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"changeCapsulesEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"projectAgentSpecEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"projectContextEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"projectChangeStateEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"apiKeyEnv":{"const":"CLEARTRACE_API_KEY"}},"additionalProperties":false},"foundationRefs":{"type":"object","required":["clearTraceHelp","evolutionPolicy","foundationSpecs"],"properties":{"clearTraceHelp":{"type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":1000}},"evolutionPolicy":{"type":"object","required":["contractId","version","updateExistingBeforeCreate","managedBundleWriteRule","triggerKinds","resolutionOrder","newSpecRegistration","evidenceRule"],"properties":{"contractId":{"const":"cleartrace-foundation-evolution-v1"},"version":{"const":1},"updateExistingBeforeCreate":{"const":true},"managedBundleWriteRule":{"type":"string","minLength":1,"maxLength":4000},"triggerKinds":{"type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":1000}},"resolutionOrder":{"type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":1000}},"newSpecRegistration":{"type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":1000}},"evidenceRule":{"type":"string","minLength":1,"maxLength":4000}},"additionalProperties":false},"foundationSpecs":{"type":"array","maxItems":500,"items":{"type":"object","required":["foundationSpecId","title","specType","pathOrUri","appliesTo","privacyMode","supportedLocales"],"properties":{"foundationSpecId":{"type":"string","minLength":1,"maxLength":256},"title":{"type":"string","minLength":1,"maxLength":500},"specType":{"type":"string","minLength":1,"maxLength":100},"pathOrUri":{"type":"string","minLength":1,"maxLength":512},"appliesTo":{"type":"string","enum":["cleartrace_product","tracked_project","both"]},"privacyMode":{"type":"string","enum":["reference_only","metadata_summary","snapshot_text","artifact_file"]},"supportedLocales":{"type":"array","maxItems":50,"items":{"type":"string","minLength":1,"maxLength":1000}}},"additionalProperties":false}}},"additionalProperties":false},"componentManifestEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"contracts":{"type":"array","maxItems":50,"items":{"type":"string","minLength":1,"maxLength":1000},"contains":{"const":"changehub-package-v1"},"minContains":1}},"additionalProperties":false}},"additionalProperties":false},{"type":"object","required":["fileName","contentType","sha256","content"],"properties":{"fileName":{"const":".cleartrace/scanner-config.json"},"contentType":{"const":"application/json"},"sha256":{"type":"string","pattern":"^sha256:[a-f0-9]{64}$"},"content":{"type":"object","required":["projectId","solutionId","projectKitId","kitVersion","schemaVersion","minimumScannerVersion","repositoryId","isOrchestrationProject","privacyMode","privacy","evidencePolicy","integration","repository","includePatterns","excludePatterns","outputContracts"],"properties":{"projectId":{"type":"string","minLength":1,"maxLength":256},"solutionId":{"type":"string","minLength":1,"maxLength":256},"projectKitId":{"type":"string","minLength":1,"maxLength":256},"kitVersion":{"type":"string","pattern":"^[0-9]+\\.[0-9]+\\.[0-9]+(?:[-+][A-Za-z0-9.-]+)?$"},"schemaVersion":{"type":"integer","minimum":1},"minimumScannerVersion":{"type":"string","pattern":"^[0-9]+\\.[0-9]+\\.[0-9]+(?:[-+][A-Za-z0-9.-]+)?$"},"repositoryId":{"anyOf":[{"type":"string","minLength":1,"maxLength":256},{"type":"null"}]},"isOrchestrationProject":{"type":"boolean"},"privacyMode":{"type":"string","enum":["reference_only","metadata_summary","snapshot_text","artifact_file"]},"privacy":{"type":"object","required":["mode","allowPatchText","allowRawSourceUpload"],"properties":{"mode":{"type":"string","enum":["reference_only","metadata_summary","snapshot_text","artifact_file"]},"allowPatchText":{"type":"boolean"},"allowRawSourceUpload":{"const":false}},"additionalProperties":false},"evidencePolicy":{"type":"object","required":["version","defaultLevel","domainOverrides"],"properties":{"version":{"const":1},"defaultLevel":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"domainOverrides":{"type":"object","properties":{"change_detail":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"system_architecture":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"cloud_and_deployment":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"data_model":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"data_flow":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"tests":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"specifications":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]}},"additionalProperties":false}},"additionalProperties":false},"integration":{"type":"object","required":["apiBaseUrl","mcpEndpoint","basePath","discovery","docs","openapi","capabilities","assistantGuide","agentSpec","developerGuide","kitLatest","kitReleases","packageLint","packageSubmitEndpoint","packageValidateEndpoint","workspaceDiscoveryPreviewEndpoint","workspaceDiscoveryApplyEndpoint","ticketValidateEndpoint","changeCapsuleValidateEndpoint","pushWriteSetPreviewEndpoint","pushWriteSetSubmitEndpoint","workingPlanResolutionEndpoint","workingPlansEndpoint","createWorkingPlanEndpoint","updateWorkingPlanEndpoint","appendWorkingPlanEventEndpoint","ticketSchema","changeCapsuleSchema","pushWriteSetSchema","searchEndpoint","ticketsEndpoint","changeCapsulesEndpoint","projectAgentSpecEndpoint","projectContextEndpoint","projectChangeStateEndpoint","apiKeyEnv"],"properties":{"apiBaseUrl":{"type":"string","minLength":1,"maxLength":1000,"pattern":"^https?://"},"mcpEndpoint":{"type":"string","minLength":1,"maxLength":1000,"pattern":"^https?://"},"basePath":{"const":"/ai-integration/v1"},"discovery":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"docs":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"openapi":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"capabilities":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"assistantGuide":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"agentSpec":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"developerGuide":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"kitLatest":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"kitReleases":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"packageLint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"packageSubmitEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"packageValidateEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"workspaceDiscoveryPreviewEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"workspaceDiscoveryApplyEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"ticketValidateEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"changeCapsuleValidateEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"pushWriteSetPreviewEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"pushWriteSetSubmitEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"workingPlanResolutionEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"workingPlansEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"createWorkingPlanEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"updateWorkingPlanEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"appendWorkingPlanEventEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"ticketSchema":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"changeCapsuleSchema":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"pushWriteSetSchema":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"searchEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"ticketsEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"changeCapsulesEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"projectAgentSpecEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"projectContextEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"projectChangeStateEndpoint":{"type":"string","minLength":1,"maxLength":2000,"pattern":"^/"},"apiKeyEnv":{"const":"CLEARTRACE_API_KEY"}},"additionalProperties":false},"repository":{"type":"object","required":["repositoryId","url","defaultBranch","mode"],"properties":{"repositoryId":{"anyOf":[{"type":"string","minLength":1,"maxLength":256},{"type":"null"}]},"url":{"anyOf":[{"type":"null"},{"type":"string","minLength":1,"maxLength":1000,"anyOf":[{"pattern":"^https://(?![^/]*@)[^\\s?#]+$"},{"pattern":"^ssh://(?:[A-Za-z0-9._-]+@)?[^\\s/?#]+/[^\\s?#]+$"},{"pattern":"^git://[^\\s/?#]+/[^\\s?#]+$"},{"pattern":"^(?:[A-Za-z0-9._-]+@)?[A-Za-z0-9.-]+:[^/\\s?#][^\\s?#]*$"}]}]},"defaultBranch":{"type":["string","null"],"minLength":1,"maxLength":256},"mode":{"type":"string","minLength":1,"maxLength":64}},"additionalProperties":false},"includePatterns":{"type":"array","maxItems":500,"items":{"type":"string","minLength":1,"maxLength":1000}},"excludePatterns":{"type":"array","maxItems":500,"items":{"type":"string","minLength":1,"maxLength":1000}},"outputContracts":{"type":"array","maxItems":50,"items":{"type":"string","minLength":1,"maxLength":1000},"contains":{"const":"changehub-package-v1"},"minContains":1}},"additionalProperties":false}},"additionalProperties":false},{"type":"object","required":["fileName","contentType","sha256","content"],"properties":{"fileName":{"const":".cleartrace/agent-spec.json"},"contentType":{"const":"application/json"},"sha256":{"type":"string","pattern":"^sha256:[a-f0-9]{64}$"},"content":{"type":"object","required":["specId","version","role","audience","sourceOfTruth","preferredAccess","requiredSequence","cliDistribution","requiredReads","validationEndpoints","writeEndpoints","workingPlanEventPolicy","writeObjectDecisionGuide","solutionEvidencePolicy","recordAuthorityPolicy","changeFinalizationPolicy","deliveryEvidencePolicy","kitUpdatePolicy","behaviorInstallationPolicy","methodologyPolicy","approvalGates","blockedActions","integrationBoundaries","aiRuntimePolicy","mcpPolicy","project","projectEndpoints"],"properties":{"firstWrite":{"type":"object","required":["briefId"],"properties":{"briefId":{"const":"cleartrace-first-write-brief-v1"}}},"packageInputLimits":{"type":"object","properties":{"localCli":{"type":"object"},"changeSummaryMaxLength":{"const":4000},"unit":{"const":"utf16_code_units"},"guidance":{"type":"string"},"guidanceLocales":{"type":"object"}},"additionalProperties":false},"specId":{"type":"string","minLength":1,"maxLength":500,"pattern":"^cleartrace-agent-spec:"},"version":{"type":"string","pattern":"^[0-9]+\\.[0-9]+\\.[0-9]+(?:[-+][A-Za-z0-9.-]+)?$"},"role":{"type":"string","minLength":1,"maxLength":500},"audience":{"type":"array","maxItems":500,"items":{"type":"string","minLength":1,"maxLength":1000}},"sourceOfTruth":{"type":"object","required":["apiBaseUrl","apiBasePath","discovery","docs","openapi","capabilities","search","assistantGuide","agentSpec","rule"],"properties":{"apiBaseUrl":{"type":"string","minLength":1,"maxLength":2000},"apiBasePath":{"type":"string","minLength":1,"maxLength":2000},"discovery":{"type":"string","minLength":1,"maxLength":2000},"docs":{"type":"string","minLength":1,"maxLength":2000},"openapi":{"type":"string","minLength":1,"maxLength":2000},"capabilities":{"type":"string","minLength":1,"maxLength":2000},"search":{"type":"string","minLength":1,"maxLength":2000},"assistantGuide":{"type":"string","minLength":1,"maxLength":2000},"agentSpec":{"type":"string","minLength":1,"maxLength":2000},"rule":{"type":"string","minLength":1,"maxLength":2000}},"additionalProperties":false},"cliDistribution":{"type":"object"},"preferredAccess":{"type":"array","maxItems":500,"items":{"type":"string","minLength":1,"maxLength":1000}},"requiredSequence":{"type":"array","maxItems":500,"items":{"type":"string","minLength":1,"maxLength":1000}},"solutionEvidencePolicy":{"type":"object","required":["version","defaultLevel","domainOverrides"],"properties":{"version":{"const":1},"defaultLevel":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"domainOverrides":{"type":"object","properties":{"change_detail":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"system_architecture":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"cloud_and_deployment":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"data_model":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"data_flow":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"tests":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]},"specifications":{"type":"string","enum":["reference_only","metadata_summary","structured_state","exact_diff","full_artifact"]}},"additionalProperties":false}},"additionalProperties":false},"requiredReads":{"type":"object","required":["discovery","openapi","capabilities","search","docs","assistantGuide","agentSpec","projectKit","kitLatest","kitReleases","projectKitDownload","projectContext","projectChangeState","projectComponents","tickets","ticketParticipants","changeCapsules","workspaceDiscoveryPreview","solutionArchitecture","architectureScanDeficits","changeCapsuleSnapshot","workingPlanResolution","workingPlans"],"properties":{"discovery":{"type":"string","minLength":1,"maxLength":2000},"openapi":{"type":"string","minLength":1,"maxLength":2000},"capabilities":{"type":"string","minLength":1,"maxLength":2000},"search":{"type":"string","minLength":1,"maxLength":2000},"docs":{"type":"string","minLength":1,"maxLength":2000},"assistantGuide":{"type":"string","minLength":1,"maxLength":2000},"agentSpec":{"type":"string","minLength":1,"maxLength":2000},"projectKit":{"type":"string","minLength":1,"maxLength":2000},"kitLatest":{"type":"string","minLength":1,"maxLength":2000},"kitReleases":{"type":"string","minLength":1,"maxLength":2000},"projectKitDownload":{"type":"string","minLength":1,"maxLength":2000},"projectContext":{"type":"string","minLength":1,"maxLength":2000},"projectChangeState":{"type":"string","minLength":1,"maxLength":2000},"projectComponents":{"type":"string","minLength":1,"maxLength":2000},"tickets":{"type":"string","minLength":1,"maxLength":2000},"ticketParticipants":{"type":"string","minLength":1,"maxLength":2000},"changeCapsules":{"type":"string","minLength":1,"maxLength":2000},"workspaceDiscoveryPreview":{"type":"string","minLength":1,"maxLength":2000},"solutionArchitecture":{"type":"string","minLength":1,"maxLength":2000},"architectureScanDeficits":{"type":"string","minLength":1,"maxLength":2000},"changeCapsuleSnapshot":{"type":"string","minLength":1,"maxLength":2000},"workingPlanResolution":{"type":"string","minLength":1,"maxLength":2000},"workingPlans":{"type":"string","minLength":1,"maxLength":2000}},"additionalProperties":false},"validationEndpoints":{"type":"object","required":["packageLint","packageValidate","ticketValidate","changeCapsuleValidate","pushWriteSetPreview","taskCloseoutPreview"],"properties":{"packageLint":{"type":"string","minLength":1,"maxLength":2000},"packageValidate":{"type":"string","minLength":1,"maxLength":2000},"ticketValidate":{"type":"string","minLength":1,"maxLength":2000},"changeCapsuleValidate":{"type":"string","minLength":1,"maxLength":2000},"pushWriteSetPreview":{"type":"string","minLength":1,"maxLength":2000},"taskCloseoutPreview":{"type":"string","minLength":1,"maxLength":2000}},"additionalProperties":false},"writeEndpoints":{"type":"object","required":["applyWorkspaceDiscovery","submitPackage","submitPushWriteSet","submitTaskCloseout","createWorkingPlan","updateWorkingPlan","appendWorkingPlanEvent"],"properties":{"applyWorkspaceDiscovery":{"type":"string","minLength":1,"maxLength":2000},"submitPackage":{"type":"string","minLength":1,"maxLength":2000},"submitPushWriteSet":{"type":"string","minLength":1,"maxLength":2000},"submitTaskCloseout":{"type":"string","minLength":1,"maxLength":2000},"createWorkingPlan":{"type":"string","minLength":1,"maxLength":2000},"updateWorkingPlan":{"type":"string","minLength":1,"maxLength":2000},"appendWorkingPlanEvent":{"type":"string","minLength":1,"maxLength":2000}},"additionalProperties":false},"workingPlanEventPolicy":{"type":"object","required":["requiredReadBeforeWrite","optimisticConcurrency","eventTypes","blockedWithoutApproval"],"properties":{"requiredReadBeforeWrite":{"const":true},"optimisticConcurrency":{"type":"string","minLength":1,"maxLength":4000},"eventTypes":{"type":"object","required":["note","decision","step_added","step_updated","status_changed"],"properties":{"note":{"type":"object","required":["required","useFor"],"properties":{"required":{"type":"array","maxItems":500,"items":{"type":"string","minLength":1,"maxLength":1000}},"useFor":{"type":"string","minLength":1,"maxLength":2000}},"additionalProperties":false},"decision":{"type":"object","required":["required","useFor"],"properties":{"required":{"type":"array","maxItems":500,"items":{"type":"string","minLength":1,"maxLength":1000}},"useFor":{"type":"string","minLength":1,"maxLength":2000}},"additionalProperties":false},"step_added":{"type":"object","required":["required","useFor"],"properties":{"required":{"type":"array","maxItems":500,"items":{"type":"string","minLength":1,"maxLength":1000}},"useFor":{"type":"string","minLength":1,"maxLength":2000}},"additionalProperties":false},"step_updated":{"type":"object","required":["required","useFor"],"properties":{"required":{"type":"array","maxItems":500,"items":{"type":"string","minLength":1,"maxLength":1000}},"useFor":{"type":"string","minLength":1,"maxLength":2000}},"additionalProperties":false},"status_changed":{"type":"object","required":["required","useFor"],"properties":{"required":{"type":"array","maxItems":500,"items":{"type":"string","minLength":1,"maxLength":1000}},"useFor":{"type":"string","minLength":1,"maxLength":2000}},"additionalProperties":false}},"additionalProperties":false},"blockedWithoutApproval":{"type":"array","maxItems":500,"items":{"type":"string","minLength":1,"maxLength":1000}}},"additionalProperties":false},"writeObjectDecisionGuide":{"type":"object","required":["purpose","requiredBeforeWrite","choices","rule"],"properties":{"purpose":{"type":"string","minLength":1,"maxLength":4000},"requiredBeforeWrite":{"type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":1000}},"choices":{"type":"object","required":["workingPlan","ticket","finding","changeCapsule"],"properties":{"workingPlan":{"type":"object","required":["useWhen","doNotUseWhen","writePath","approval"],"properties":{"useWhen":{"type":"string","minLength":1,"maxLength":4000},"doNotUseWhen":{"type":"string","minLength":1,"maxLength":4000},"writePath":{"type":"string","minLength":1,"maxLength":4000},"approval":{"type":"string","minLength":1,"maxLength":4000}},"additionalProperties":false},"ticket":{"type":"object","required":["useWhen","doNotUseWhen","schema","validationEndpoint","submitEndpoint","pushType","requiredPayload","recommendedPayload","recommendedRefs","relationshipRule","terminalLifecycleRule"],"properties":{"useWhen":{"type":"string","minLength":1,"maxLength":4000},"doNotUseWhen":{"type":"string","minLength":1,"maxLength":4000},"schema":{"type":"string","minLength":1,"maxLength":4000},"validationEndpoint":{"type":"string","minLength":1,"maxLength":4000},"submitEndpoint":{"type":"string","minLength":1,"maxLength":4000},"pushType":{"const":"ticket"},"requiredPayload":{"type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":1000}},"recommendedPayload":{"type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":1000}},"recommendedRefs":{"type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":1000}},"relationshipRule":{"type":"string","minLength":1,"maxLength":4000},"terminalLifecycleRule":{"type":"string","minLength":1,"maxLength":4000}},"additionalProperties":false},"finding":{"type":"object","required":["useWhen","doNotUseWhen","validationEndpoint","submitEndpoint","pushType","requiredRefs"],"properties":{"useWhen":{"type":"string","minLength":1,"maxLength":4000},"doNotUseWhen":{"type":"string","minLength":1,"maxLength":4000},"validationEndpoint":{"type":"string","minLength":1,"maxLength":4000},"submitEndpoint":{"type":"string","minLength":1,"maxLength":4000},"pushType":{"const":"finding"},"requiredRefs":{"type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":1000}}},"additionalProperties":false},"changeCapsule":{"type":"object","required":["useWhen","doNotUseWhen","schema","validationEndpoint","submitEndpoint","pushType","requiredPayload","recommendedPayload","recommendedRefs"],"properties":{"useWhen":{"type":"string","minLength":1,"maxLength":4000},"doNotUseWhen":{"type":"string","minLength":1,"maxLength":4000},"schema":{"type":"string","minLength":1,"maxLength":4000},"validationEndpoint":{"type":"string","minLength":1,"maxLength":4000},"submitEndpoint":{"type":"string","minLength":1,"maxLength":4000},"pushType":{"const":"change_capsule"},"requiredPayload":{"type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":1000}},"recommendedPayload":{"type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":1000}},"recommendedRefs":{"type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":1000}}},"additionalProperties":false}},"additionalProperties":false},"rule":{"type":"string","minLength":1,"maxLength":4000}},"additionalProperties":false},"recordAuthorityPolicy":{"type":"object","required":["contractId","version","records","ticketPolicy","planOwnership","testingProjectPolicy","mirrorPolicy","changeClassification"],"properties":{"contractId":{"const":"cleartrace-record-authority-v1"},"version":{"const":1},"records":{"type":"object","required":["sourceAndCommits","solutionCoordination","projectMethodology","hostedWorkflowLedger","transientGeneratedOutput"],"properties":{"sourceAndCommits":{"const":"git_when_available"},"solutionCoordination":{"const":"orchestration_repository"},"projectMethodology":{"const":"owning_project_repository"},"hostedWorkflowLedger":{"const":"cleartrace_after_accepted_ingestion"},"transientGeneratedOutput":{"const":".cleartrace/out"}},"additionalProperties":false},"ticketPolicy":{"type":"object","required":["ticketRequiredForEveryChange","planDrivenChangeAllowed","createOrReuseWhen","changeEvidenceRequiredWhenFilesChange","rule"],"properties":{"ticketRequiredForEveryChange":{"const":false},"planDrivenChangeAllowed":{"const":true},"createOrReuseWhen":{"type":"array","maxItems":500,"items":{"type":"string","minLength":1,"maxLength":1000}},"changeEvidenceRequiredWhenFilesChange":{"const":true},"rule":{"type":"string","minLength":1,"maxLength":4000}},"additionalProperties":false},"planOwnership":{"type":"object","required":["solutionLevel","projectLevel","hostedProjection","rule"],"properties":{"solutionLevel":{"const":"orchestration_repository_when_configured"},"projectLevel":{"const":"affected_project_repository"},"hostedProjection":{"const":"cleartrace_working_plan"},"rule":{"type":"string","minLength":1,"maxLength":4000}},"additionalProperties":false},"testingProjectPolicy":{"type":"object","required":["projectFunction","isOrchestrationProject","runtimeArchitectureByRegistration","localEvidenceOwners","hostedWorkflowOwners","rule"],"properties":{"projectFunction":{"type":["string","null"],"maxLength":500},"isOrchestrationProject":{"type":"boolean"},"runtimeArchitectureByRegistration":{"const":false},"localEvidenceOwners":{"type":"array","maxItems":500,"items":{"type":"string","minLength":1,"maxLength":1000}},"hostedWorkflowOwners":{"type":"array","maxItems":500,"items":{"type":"string","minLength":1,"maxLength":1000}},"rule":{"type":"string","minLength":1,"maxLength":4000}},"additionalProperties":false},"mirrorPolicy":{"type":"object","required":["createLocalTicketLedger","createLocalFindingLedger","createLocalChangeCapsuleLedger","preserveLocally","rule"],"properties":{"createLocalTicketLedger":{"const":false},"createLocalFindingLedger":{"const":false},"createLocalChangeCapsuleLedger":{"const":false},"preserveLocally":{"type":"array","maxItems":500,"items":{"type":"string","minLength":1,"maxLength":1000}},"rule":{"type":"string","minLength":1,"maxLength":4000}},"additionalProperties":false},"changeClassification":{"type":"object","required":["requiredWhen","domains","deterministicFacts","assistantNarrative","ticketLinkRequired","currentStateRule"],"properties":{"requiredWhen":{"const":"local_files_changed"},"domains":{"type":"array","maxItems":500,"items":{"type":"string","minLength":1,"maxLength":1000}},"deterministicFacts":{"type":"array","maxItems":500,"items":{"type":"string","minLength":1,"maxLength":1000}},"assistantNarrative":{"type":"array","maxItems":500,"items":{"type":"string","minLength":1,"maxLength":1000}},"ticketLinkRequired":{"const":false},"currentStateRule":{"type":"string","minLength":1,"maxLength":4000}},"additionalProperties":false}},"additionalProperties":false},"changeFinalizationPolicy":{"type":"object","required":["contractId","unitOfRecord","taskMetadataRequired","trigger","commitPolicy","evidencePolicy","objectResolution","multiRepository","authorization"],"properties":{"contractId":{"const":"cleartrace-change-finalization-v1"},"unitOfRecord":{"const":"discrete_user_requested_change"},"taskMetadataRequired":{"const":false},"trigger":{"const":"local_files_changed"},"commitPolicy":{"type":"object","required":["commitRequiredWhenGitAvailable","nonGitEvidenceAllowed","clearTraceSubmissionIndependent","commitTrackedScopeOnly","pushWhenAuthorized","noEmptyCommit","preserveUnrelatedChanges"],"properties":{"commitRequiredWhenGitAvailable":{"const":true},"nonGitEvidenceAllowed":{"const":true},"clearTraceSubmissionIndependent":{"const":true},"commitTrackedScopeOnly":{"const":true},"pushWhenAuthorized":{"const":true},"noEmptyCommit":{"const":true},"preserveUnrelatedChanges":{"const":true}},"additionalProperties":false},"evidencePolicy":{"type":"object","required":["requiredBeforeCompletion","packageType","changeContractId","validateBeforeSubmit","submitWhenAuthorized","failureOutputDirectory","previewCommand","submitCommand","closeoutPreviewCommand","closeoutSubmitCommand","captureTaskStartHead","singleApprovalCloseout","taskBeginCommand","taskExtendCommand","taskStatusCommand","taskCheckpointCommand","taskCloseoutPreviewCommand","taskCloseoutSubmitCommand","taskStartCommand","taskAddRootCommand","taskPreviewCommand","taskSubmitCommand","deterministicTaskSession","outcomes","commitIndependentCapture","classificationRequired","classificationDomains","deterministicFacts","assistantNarrative","ticketLinkRequired"],"properties":{"requiredBeforeCompletion":{"const":true},"packageType":{"const":"change_capsule"},"changeContractId":{"const":"cleartrace-change-evidence-v1"},"validateBeforeSubmit":{"const":true},"submitWhenAuthorized":{"const":true},"failureOutputDirectory":{"const":".cleartrace/out"},"previewCommand":{"type":"string","minLength":1,"maxLength":4000},"submitCommand":{"type":"string","minLength":1,"maxLength":4000},"closeoutPreviewCommand":{"type":"string","minLength":1,"maxLength":4000},"closeoutSubmitCommand":{"type":"string","minLength":1,"maxLength":4000},"taskBeginCommand":{"type":"string","minLength":1,"maxLength":4000},"taskExtendCommand":{"type":"string","minLength":1,"maxLength":4000},"taskCloseoutPreviewCommand":{"type":"string","minLength":1,"maxLength":4000},"taskCloseoutSubmitCommand":{"type":"string","minLength":1,"maxLength":4000},"taskStartCommand":{"type":"string","minLength":1,"maxLength":4000},"taskAddRootCommand":{"type":"string","minLength":1,"maxLength":4000},"taskStatusCommand":{"type":"string","minLength":1,"maxLength":4000},"taskCheckpointCommand":{"type":"string","minLength":1,"maxLength":4000},"taskPreviewCommand":{"type":"string","minLength":1,"maxLength":4000},"taskSubmitCommand":{"type":"string","minLength":1,"maxLength":4000},"deterministicTaskSession":{"const":true},"captureTaskStartHead":{"const":true},"singleApprovalCloseout":{"const":true},"outcomes":{"type":"array","const":["completed","partial","failed"]},"commitIndependentCapture":{"const":true},"classificationRequired":{"const":true},"classificationDomains":{"type":"array","maxItems":500,"items":{"type":"string","minLength":1,"maxLength":1000}},"deterministicFacts":{"type":"array","maxItems":500,"items":{"type":"string","minLength":1,"maxLength":1000}},"assistantNarrative":{"type":"array","maxItems":500,"items":{"type":"string","minLength":1,"maxLength":1000}},"ticketLinkRequired":{"const":false}},"additionalProperties":false},"objectResolution":{"type":"object","required":["strategy","identityInputs","rule"],"properties":{"strategy":{"const":"stable_identity_first"},"identityInputs":{"type":"array","maxItems":500,"items":{"type":"string","minLength":1,"maxLength":1000}},"rule":{"type":"string","minLength":1,"maxLength":4000}},"additionalProperties":false},"multiRepository":{"type":"object","required":["sharedChangeCapsuleId","perRepositoryPackage","projectScopedPackageWithoutRepository","rule"],"properties":{"sharedChangeCapsuleId":{"const":true},"perRepositoryPackage":{"const":true},"projectScopedPackageWithoutRepository":{"const":true},"rule":{"type":"string","minLength":1,"maxLength":4000}},"additionalProperties":false},"authorization":{"type":"object","required":["standingAuthorizationAllowed","exactBoundaryRequired","separateApprovalActions"],"properties":{"standingAuthorizationAllowed":{"const":true},"exactBoundaryRequired":{"const":true},"separateApprovalActions":{"type":"array","maxItems":500,"items":{"type":"string","minLength":1,"maxLength":1000}}},"additionalProperties":false}},"additionalProperties":false},"deliveryEvidencePolicy":{"type":"object"},"kitUpdatePolicy":{"type":"object"},"behaviorInstallationPolicy":{"type":"object"},"methodologyPolicy":{"type":"object","required":["contractId","version","methodologyMode","repositoryRole","canonicalAuthority","projectTopology","foundationEvolution","assistantAdapters"],"properties":{"contractId":{"const":"cleartrace-methodology-behavior-v1"},"version":{"const":1},"methodologyMode":{"enum":["acdc","inferred","custom"]},"repositoryRole":{"enum":["orchestration","product","generic"]},"canonicalAuthority":{"type":"object","required":["sourceAndCommits","localTopology","projectBehavior","hostedCatalog","ticketsAndEvidence","rule"],"properties":{"sourceAndCommits":{"const":"git"},"localTopology":{"const":"orchestration_repository_registry"},"projectBehavior":{"const":"referenced_local_specs"},"hostedCatalog":{"const":"cleartrace"},"ticketsAndEvidence":{"const":"cleartrace_after_accepted_ingestion"},"rule":{"type":"string","minLength":1,"maxLength":4000}},"additionalProperties":false},"projectTopology":{"type":"object","required":["orchestrationProjectId","localRegistryCandidates","triggers","requiredUpdates","crossRepositoryRule","hostedCatalogRule"],"properties":{"orchestrationProjectId":{"type":["string","null"],"maxLength":500},"localRegistryCandidates":{"type":"array","maxItems":500,"items":{"type":"string","minLength":1,"maxLength":1000}},"triggers":{"type":"array","maxItems":500,"items":{"type":"string","minLength":1,"maxLength":1000}},"requiredUpdates":{"type":"array","maxItems":500,"items":{"type":"string","minLength":1,"maxLength":1000}},"crossRepositoryRule":{"type":"string","minLength":1,"maxLength":4000},"hostedCatalogRule":{"type":"string","minLength":1,"maxLength":4000}},"additionalProperties":false},"foundationEvolution":{"type":"object","required":["triggers","resolutionOrder","updateRule","creationRule","registrationRule"],"properties":{"triggers":{"type":"array","maxItems":500,"items":{"type":"string","minLength":1,"maxLength":1000}},"resolutionOrder":{"type":"array","maxItems":500,"items":{"type":"string","minLength":1,"maxLength":1000}},"updateRule":{"type":"string","minLength":1,"maxLength":4000},"creationRule":{"type":"string","minLength":1,"maxLength":4000},"registrationRule":{"type":"string","minLength":1,"maxLength":4000}},"additionalProperties":false},"assistantAdapters":{"type":"object","required":["canonicalPolicy","codex","claude","preserveExistingInstructions","setupRule"],"properties":{"canonicalPolicy":{"const":".cleartrace/agent-spec.json"},"codex":{"type":"object","required":["entrypoint","adapterCommand"],"properties":{"entrypoint":{"type":"string","minLength":1,"maxLength":2000},"adapterCommand":{"type":"string","minLength":1,"maxLength":2000}},"additionalProperties":false},"claude":{"type":"object","required":["entrypoint","adapterCommand"],"properties":{"entrypoint":{"type":"string","minLength":1,"maxLength":2000},"adapterCommand":{"type":"string","minLength":1,"maxLength":2000}},"additionalProperties":false},"preserveExistingInstructions":{"const":true},"setupRule":{"type":"string","minLength":1,"maxLength":4000}},"additionalProperties":false}},"additionalProperties":false},"approvalGates":{"type":"array","maxItems":500,"items":{"type":"string","minLength":1,"maxLength":1000}},"blockedActions":{"type":"array","maxItems":500,"items":{"type":"string","minLength":1,"maxLength":1000}},"integrationBoundaries":{"type":"object"},"aiRuntimePolicy":{"type":"object","required":["routeRequired","routeSource","resolver","blockedWhen","blockedErrorCodes","taskRouteStatus"],"properties":{"routeRequired":{"const":true},"routeSource":{"type":"string","minLength":1,"maxLength":500},"resolver":{"type":"string","minLength":1,"maxLength":500},"blockedWhen":{"type":"array","maxItems":500,"items":{"type":"string","minLength":1,"maxLength":1000}},"blockedErrorCodes":{"type":"array","maxItems":500,"items":{"type":"string","minLength":1,"maxLength":1000}},"taskRouteStatus":{"type":"array","maxItems":100,"items":{"type":"object","required":["taskType","status","isEnabled","providerConnectionId","providerLabel","providerId","providerStatus","modelId","reasoningLevel"],"properties":{"taskType":{"type":"string","minLength":1},"status":{"type":"string","minLength":1},"isEnabled":{"type":"boolean"},"providerConnectionId":{"type":["string","null"]},"providerLabel":{"type":["string","null"]},"providerId":{"type":["string","null"]},"providerStatus":{"type":["string","null"]},"modelId":{"type":["string","null"]},"reasoningLevel":{"type":["string","null"]}},"additionalProperties":false}}},"additionalProperties":false},"mcpPolicy":{"type":"object","required":["currentMode","mcpStatus","rule","servicePackage","productionTarget","firstTools"],"properties":{"currentMode":{"const":"openapi_first"},"mcpStatus":{"type":"string","minLength":1},"rule":{"type":"string","minLength":1},"servicePackage":{"type":"string","minLength":1},"productionTarget":{"type":"string","minLength":1},"firstTools":{"type":"array","maxItems":500,"items":{"type":"string","minLength":1,"maxLength":1000}}},"additionalProperties":false},"project":{"type":"object","required":["projectId","projectName","projectFunction","solutionId","solutionName","repositoryUrl","connectionMode","connectionModeBlocker","privacyMode","methodologyMode","repositoryRole","orchestrationProjectId"],"properties":{"projectId":{"type":"string","minLength":1,"maxLength":256},"projectName":{"type":"string","minLength":1},"projectFunction":{"type":"string","minLength":1,"maxLength":256},"solutionId":{"type":"string","minLength":1,"maxLength":256},"solutionName":{"type":["string","null"]},"repositoryUrl":{"type":["string","null"],"minLength":1},"connectionMode":{"type":["string","null"],"enum":["local_scanner","external_producer","catalog_only",null]},"connectionModeBlocker":{"type":["string","null"]},"privacyMode":{"type":"string","enum":["reference_only","metadata_summary","snapshot_text","artifact_file"]},"methodologyMode":{"enum":["acdc","inferred","custom"]},"repositoryRole":{"enum":["orchestration","product"]},"orchestrationProjectId":{"type":["string","null"],"maxLength":500}},"additionalProperties":false},"projectEndpoints":{"type":"object","required":["detail","download","scannerConfig","foundation","agentSpec","context","ticketParticipants","changeState","tickets","changeCapsules","workingPlanResolution","workingPlans","components","componentManifests"],"properties":{"detail":{"type":"string","minLength":1,"maxLength":2000},"download":{"type":"string","minLength":1,"maxLength":2000},"scannerConfig":{"type":"string","minLength":1,"maxLength":2000},"foundation":{"type":"string","minLength":1,"maxLength":2000},"agentSpec":{"type":"string","minLength":1,"maxLength":2000},"context":{"type":"string","minLength":1,"maxLength":2000},"ticketParticipants":{"type":"string","minLength":1,"maxLength":2000},"changeState":{"type":"string","minLength":1,"maxLength":2000},"tickets":{"type":"string","minLength":1,"maxLength":2000},"changeCapsules":{"type":"string","minLength":1,"maxLength":2000},"workingPlanResolution":{"type":"string","minLength":1,"maxLength":2000},"workingPlans":{"type":"string","minLength":1,"maxLength":2000},"components":{"type":"string","minLength":1,"maxLength":2000},"componentManifests":{"type":"string","minLength":1,"maxLength":2000}},"additionalProperties":false}},"additionalProperties":false}},"additionalProperties":false},{"type":"object","required":["fileName","contentType","sha256","content"],"properties":{"fileName":{"const":".cleartrace/foundation.json"},"contentType":{"const":"application/json"},"sha256":{"type":"string","pattern":"^sha256:[a-f0-9]{64}$"},"content":{"type":"object","required":["clearTraceHelp","evolutionPolicy","foundationSpecs"],"properties":{"clearTraceHelp":{"type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":1000}},"evolutionPolicy":{"type":"object","required":["contractId","version","updateExistingBeforeCreate","managedBundleWriteRule","triggerKinds","resolutionOrder","newSpecRegistration","evidenceRule"],"properties":{"contractId":{"const":"cleartrace-foundation-evolution-v1"},"version":{"const":1},"updateExistingBeforeCreate":{"const":true},"managedBundleWriteRule":{"type":"string","minLength":1,"maxLength":4000},"triggerKinds":{"type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":1000}},"resolutionOrder":{"type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":1000}},"newSpecRegistration":{"type":"array","maxItems":100,"items":{"type":"string","minLength":1,"maxLength":1000}},"evidenceRule":{"type":"string","minLength":1,"maxLength":4000}},"additionalProperties":false},"foundationSpecs":{"type":"array","maxItems":500,"items":{"type":"object","required":["foundationSpecId","title","specType","pathOrUri","appliesTo","privacyMode","supportedLocales"],"properties":{"foundationSpecId":{"type":"string","minLength":1,"maxLength":256},"title":{"type":"string","minLength":1,"maxLength":500},"specType":{"type":"string","minLength":1,"maxLength":100},"pathOrUri":{"type":"string","minLength":1,"maxLength":512},"appliesTo":{"type":"string","enum":["cleartrace_product","tracked_project","both"]},"privacyMode":{"type":"string","enum":["reference_only","metadata_summary","snapshot_text","artifact_file"]},"supportedLocales":{"type":"array","maxItems":50,"items":{"type":"string","minLength":1,"maxLength":1000}}},"additionalProperties":false}}},"additionalProperties":false}},"additionalProperties":false},{"type":"object","required":["fileName","contentType","sha256","content"],"properties":{"fileName":{"const":".cleartrace/components.json"},"contentType":{"const":"application/json"},"sha256":{"type":"string","pattern":"^sha256:[a-f0-9]{64}$"},"content":{"type":"array","maxItems":500,"items":{"type":"object","required":["componentId","solutionId","projectId","repositoryId","name","componentType","rootPath","sourcePaths","specPaths","guidancePaths","appFoundationPaths","codingConventionPaths","dataModelPaths","dataFlowPaths","evidencePaths","localization","styleModes"],"properties":{"componentId":{"type":"string","minLength":1,"maxLength":256},"solutionId":{"type":"string","minLength":1,"maxLength":256},"projectId":{"anyOf":[{"type":"string","minLength":1,"maxLength":256},{"type":"null"}]},"repositoryId":{"type":"string","minLength":1,"maxLength":256},"name":{"type":"string","minLength":1,"maxLength":500},"componentType":{"type":"string","minLength":1,"maxLength":100},"rootPath":{"type":"string","minLength":1,"maxLength":512,"pattern":"^(?:\\.|(?!/)(?!.*\\\\)(?!.*//)(?!.*(?:^|/)\\.\\.?(?:/|$))[^\\u0000-\\u001f]+)$"},"sourcePaths":{"type":"array","maxItems":2000,"items":{"type":"string","minLength":1,"maxLength":512,"pattern":"^(?!/)(?!.*\\\\)(?!.*//)(?!.*(?:^|/)\\.\\.?(?:/|$))[^\\u0000-\\u001f]+$"}},"specPaths":{"type":"array","maxItems":2000,"items":{"type":"string","minLength":1,"maxLength":512,"pattern":"^(?!/)(?!.*\\\\)(?!.*//)(?!.*(?:^|/)\\.\\.?(?:/|$))[^\\u0000-\\u001f]+$"}},"guidancePaths":{"type":"array","maxItems":2000,"items":{"type":"string","minLength":1,"maxLength":512,"pattern":"^(?!/)(?!.*\\\\)(?!.*//)(?!.*(?:^|/)\\.\\.?(?:/|$))[^\\u0000-\\u001f]+$"}},"appFoundationPaths":{"type":"array","maxItems":2000,"items":{"type":"string","minLength":1,"maxLength":512,"pattern":"^(?!/)(?!.*\\\\)(?!.*//)(?!.*(?:^|/)\\.\\.?(?:/|$))[^\\u0000-\\u001f]+$"}},"codingConventionPaths":{"type":"array","maxItems":2000,"items":{"type":"string","minLength":1,"maxLength":512,"pattern":"^(?!/)(?!.*\\\\)(?!.*//)(?!.*(?:^|/)\\.\\.?(?:/|$))[^\\u0000-\\u001f]+$"}},"dataModelPaths":{"type":"array","maxItems":2000,"items":{"type":"string","minLength":1,"maxLength":512,"pattern":"^(?!/)(?!.*\\\\)(?!.*//)(?!.*(?:^|/)\\.\\.?(?:/|$))[^\\u0000-\\u001f]+$"}},"dataFlowPaths":{"type":"array","maxItems":2000,"items":{"type":"string","minLength":1,"maxLength":512,"pattern":"^(?!/)(?!.*\\\\)(?!.*//)(?!.*(?:^|/)\\.\\.?(?:/|$))[^\\u0000-\\u001f]+$"}},"evidencePaths":{"type":"array","maxItems":2000,"items":{"type":"string","minLength":1,"maxLength":512,"pattern":"^(?!/)(?!.*\\\\)(?!.*//)(?!.*(?:^|/)\\.\\.?(?:/|$))[^\\u0000-\\u001f]+$"}},"localization":{"type":"object"},"styleModes":{"type":"object"}},"additionalProperties":false}}},"additionalProperties":false}],"items":false},"install":{"type":"object","required":["rootDirectory","overwritePolicy","secretPolicy"],"properties":{"rootDirectory":{"const":".cleartrace"},"overwritePolicy":{"const":"review_each_file"},"secretPolicy":{"const":"store CLEARTRACE_API_KEY in the environment; never write it into kit files"}},"additionalProperties":false},"bundleHash":{"type":"string","pattern":"^sha256:[a-f0-9]{64}$"}},"additionalProperties":false},"ProjectKitBundleResponse":{"type":"object","required":["data"],"properties":{"data":{"$ref":"#/components/schemas/ProjectKitBundle"}},"additionalProperties":false},"AgentSpec":{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://api.cleartrace.dev/ai-integration/v1/schemas/agent-spec.schema.json","title":"ClearTrace Agent Spec","type":"object","required":["specId","version","role","sourceOfTruth","requiredSequence","blockedActions","aiRuntimePolicy"],"properties":{"specId":{"type":"string"},"version":{"type":"string"},"role":{"type":"string"},"audience":{"type":"array","items":{"type":"string"}},"sourceOfTruth":{"type":"object"},"requiredSequence":{"type":"array","items":{"type":"string"}},"requiredReads":{"type":"object"},"integrationBoundaries":{"type":"object"},"approvalGates":{"type":"array","items":{"type":"string"}},"blockedActions":{"type":"array","items":{"type":"string"}},"aiRuntimePolicy":{"type":"object"},"mcpPolicy":{"type":"object"},"project":{"type":["object","null"]},"projectEndpoints":{"type":["object","null"]}},"additionalProperties":true},"IntegrationCapabilities":{"title":"ClearTrace Integration Capabilities","type":"object","properties":{"version":{"type":"string"},"key":{"type":"object"},"actorContext":{"type":"object"},"capabilities":{"type":"object"},"visibleBoundary":{"type":"object"},"operatingBoundaries":{"type":"object"},"endpoints":{"type":"object"},"recommendedSequence":{"type":"array","items":{"type":"string"}},"intake":{"type":"object","properties":{"newItems":{"type":["integer","null"]},"review":{"type":"string"},"playbook":{"type":"string"}}},"github":{"type":"object","properties":{"connected":{"type":"boolean"},"playbook":{"type":"string"},"projects":{"type":"array","items":{"type":"object","properties":{"projectId":{"type":"string"},"diffSource":{"type":"string","enum":["github","upload"]}}}}}}},"additionalProperties":true},"AgentSearchRequest":{"type":"object","required":["query"],"properties":{"query":{"type":"string","minLength":2,"maxLength":240},"mode":{"type":"string","enum":["auto","deterministic","hybrid"],"default":"auto"},"solutionId":{"type":"string","maxLength":160},"projectId":{"type":"string","maxLength":160},"objectTypes":{"type":"array","minItems":1,"uniqueItems":true,"items":{"type":"string","enum":["ticket","change_capsule"]}},"statuses":{"type":"array","maxItems":10,"uniqueItems":true,"items":{"type":"string","maxLength":80}},"from":{"type":"string","format":"date-time"},"to":{"type":"string","format":"date-time"},"limit":{"type":"integer","minimum":1,"maximum":25,"default":10},"cursor":{"type":"string","maxLength":1000}},"additionalProperties":false},"FileDiffReadResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"object","required":["contractId","version","fileChangeId","filePath","previousFilePath","format","sha256","byteSize","oldPath","newPath","binary","hunks"],"properties":{"contractId":{"const":"cleartrace-file-diff-read-v1"},"version":{"const":1},"fileChangeId":{"type":"string"},"filePath":{"type":"string"},"previousFilePath":{"type":["string","null"]},"format":{"const":"git_unified_diff"},"sha256":{"type":"string","pattern":"^sha256:[a-f0-9]{64}$"},"byteSize":{"type":"integer","minimum":0},"oldPath":{"type":["string","null"]},"newPath":{"type":["string","null"]},"binary":{"type":"boolean"},"hunks":{"type":"array","items":{"type":"object","required":["header","oldStart","oldLines","newStart","newLines","section","lines"],"properties":{"header":{"type":"string"},"oldStart":{"type":"integer","minimum":0},"oldLines":{"type":"integer","minimum":0},"newStart":{"type":"integer","minimum":0},"newLines":{"type":"integer","minimum":0},"section":{"type":["string","null"]},"lines":{"type":"array","items":{"type":"object","required":["type","content","oldLineNumber","newLineNumber"],"properties":{"type":{"type":"string","enum":["context","addition","deletion","marker"]},"content":{"type":"string"},"oldLineNumber":{"type":["integer","null"],"minimum":0},"newLineNumber":{"type":["integer","null"],"minimum":0}},"additionalProperties":false}}},"additionalProperties":false}}},"additionalProperties":false}},"additionalProperties":false},"WorkingPlanCreateRequest":{"type":"object","required":["title","objective"],"properties":{"title":{"type":"string"},"objective":{"type":"string"},"visibility":{"type":"string","enum":["private","team"],"default":"private"},"scopeType":{"type":"string","enum":["workspace","solution","project","ticket","change_capsule"]},"solutionId":{"type":["string","null"]},"projectId":{"type":["string","null"]},"ticketId":{"type":["string","null"]},"changeCapsuleId":{"type":["string","null"]},"status":{"type":"string","enum":["draft","active","paused","completed","superseded"],"default":"active"},"sourceRefs":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object"}},"additionalProperties":false},"WorkingPlanUpdateRequest":{"type":"object","properties":{"expectedVersion":{"type":"integer","minimum":1},"title":{"type":"string"},"objective":{"type":"string"},"visibility":{"type":"string","enum":["private","team"]},"scopeType":{"type":"string","enum":["workspace","solution","project","ticket","change_capsule"]},"solutionId":{"type":["string","null"]},"projectId":{"type":["string","null"]},"ticketId":{"type":["string","null"]},"changeCapsuleId":{"type":["string","null"]},"status":{"type":"string","enum":["draft","active","paused","completed","superseded"]},"sourceRefs":{"type":"array","items":{"type":"string"}},"metadata":{"type":"object"},"completedAt":{"type":["string","null"],"format":"date-time"},"supersededByPlanId":{"type":["string","null"]}},"additionalProperties":false},"WorkingPlanEventRequest":{"type":"object","required":["eventType"],"properties":{"expectedVersion":{"type":"integer","minimum":1,"description":"Latest working-plan version read by the assistant. Send this to prevent stale progress writes."},"eventType":{"type":"string","enum":["note","decision","step_added","step_updated","status_changed"],"description":"Event kind. note and decision require summary; step_added requires title; step_updated requires stepId; status_changed uses metadata.status."},"title":{"type":["string","null"],"description":"Short title for step_added or rationale headline for decision."},"summary":{"type":["string","null"],"description":"Progress note, decision text, or step summary."},"stepId":{"type":["string","null"],"description":"Existing step ID for step_updated, or optional caller-provided ID for step_added."},"stepStatus":{"type":["string","null"],"enum":["pending","in_progress","completed","blocked",null],"description":"New step state for step_added or step_updated."},"sourceRefs":{"type":"array","items":{"type":"string"},"description":"Source references such as codex-thread, repo, commit, ticket, or project refs."},"metadata":{"type":"object","description":"Additional structured context. For status_changed, set metadata.status to active, paused, completed, or superseded."}},"examples":[{"expectedVersion":3,"eventType":"step_updated","stepId":"working-plan-step-abc123","stepStatus":"completed","summary":"Added API resolver and MCP wrapper, then verified scoped-key reads.","sourceRefs":["codex-thread:current","commit:53e2d16"],"metadata":{"phase":"mcp-api-enhancement"}}],"additionalProperties":false}}}}