{"data":{"product":"cleartrace","name":"ClearTrace AI integration","version":"v1","integrationBaseUrl":"https://api.cleartrace.dev/ai-integration/v1","contract":{"agentSpecVersion":"0.31.14","changes":"https://api.cleartrace.dev/ai-integration/v1/contract-changes?since={yourAgentSpecVersion}","latest":[{"changeId":"solution-flow-services","agentSpecVersion":"0.31.14","kind":"changed","summary":"CLI 0.1.108: a data-flow step may name a service that another project of the solution declares. Before a scan or closeout that includes data_flow in a repository with architecture/cleartrace-flows.json, the CLI reads the solution's declared services (best effort), so an orchestration project's flows no longer report step_service_not_declared for them. A scan or change submit whose hash differs from its preview now names the option that changed, such as --agent, instead of only evidence_submission_plan_stale; firstWrite.identity says to pass the same --agent on a preview and its submit.","searchPatterns":["step_service_not_declared","evidence_submission_plan_stale"]},{"changeId":"operation-run-cli","agentSpecVersion":"0.31.13","kind":"added","summary":"Operation runs from the CLI with the profile key (CLI 0.1.107). With a change: cleartrace task closeout preview --operation-runs <file>, or operationRuns in a closeout manifest. Without a new code change (a deploy of commits already recorded, a backup, a rotation): cleartrace operation-run preview|submit, backed by the new POST /ai-integration/v1/solutions/{solutionId}/operation-runs/preview and /operation-runs routes (push:package for the project; an identical retry answers already_applied).","searchPatterns":["does not send operationRuns","operationRuns[^\\n]*(API or MCP)"]},{"changeId":"change-outcome-field","agentSpecVersion":"0.31.12","kind":"changed","summary":"A change record's outcome (completed, partial or failed) is payload.outcome; firstWrite.doors.ticketFindingTestRunOrChange now says so. A change revision sent as a write set with the outcome only as payload.verification.outcome or payload.status has it moved to payload.outcome at preview (normalization change_outcome_promoted), so it no longer stays \"Awaiting outcome\".","searchPatterns":["verification\\W+outcome"]},{"changeId":"kit-upgrade-closeouts","agentSpecVersion":"0.31.11","kind":"changed","summary":"A closeout whose Git range includes a kit upgrade no longer fails with machine_local_path on .cleartrace/agent-spec.json: the check accepts the generic profile location ~/.config/cleartrace/connections.json that kits up to 0.31.10 carry, and firstWrite.keyHandling now names the folder without a home path. CLI 0.1.105: evidence_project_kit_unavailable says which kit file, why (missing, unreadable, invalid JSON) and which folder; a manifest repo written as /c/..., /mnt/c/... or /cygdrive/c/... is read as C:\\... on Windows; kit files with a byte-order mark are read.","searchPatterns":["evidence_project_kit_unavailable","machine_local_path"]},{"changeId":"write-set-report-mcp-cli","agentSpecVersion":"0.31.10","kind":"added","summary":"CLI 0.1.104 adds cleartrace write-set preview|submit (tickets, findings, test runs and change records without a code closeout), cleartrace report (a problem with ClearTrace itself) and cleartrace mcp (a local MCP bridge for Claude, Codex or any client). All three load the API key from the solution profile and read the solution and project from the repository's kit. firstWrite.keyHandling now says never to ask the user to put the key in an environment variable or paste it into a client; firstWrite.mcp says how to configure the bridge.","searchPatterns":["ingest/write-sets[^\\n]*(CLEARTRACE_API_KEY|X-ClearTrace-Api-Key)","cleartrace-reports","mcp\\.cleartrace\\.dev/mcp"]}]},"packageInputLimits":{"localCli":{"changeCapsuleId":500,"title":500,"summary":4000,"changedFile":2000},"changeSummaryMaxLength":4000,"unit":"utf16_code_units","guidance":"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.","guidanceLocales":{"en":"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.","es":"Resumen del cambio: 1–4000 unidades UTF-16 después de quitar espacios de los extremos. CLI local: identificador y título de cápsula, 1–500; cada ruta de archivo cambiado, 1–2000. Estos límites son del resumen y los metadatos, no del código, diff o evidencia. Conserve el detalle en la evidencia. Los errores incluyen campo, longitud actual, mínimo, máximo, unidad y recoveryAction=fix_request; no trunque ni envíe una vista previa fallida."}},"requestLimits":{"evidenceJsonBytes":33554432,"evidencePaths":["/ai-integration/v1/package-lint","/ai-integration/v1/tickets/validate","/ai-integration/v1/change-capsules/validate","/ai-integration/v1/ingest/write-sets/preview","/ai-integration/v1/ingest/write-sets","/ai-integration/v1/ingest/task-closeouts/preview","/ai-integration/v1/ingest/task-closeouts","/ai-integration/v1/ingest/packages/validate","/ai-integration/v1/ingest/packages"],"oversizedRequestStatus":413},"mcpEndpoint":"https://mcp.cleartrace.dev/mcp","docs":"https://api.cleartrace.dev/ai-integration/v1/docs","openapi":"https://api.cleartrace.dev/ai-integration/v1/openapi.json","assistantGuide":"https://api.cleartrace.dev/ai-integration/v1/assistant-guide","agentSpec":"https://api.cleartrace.dev/ai-integration/v1/agent-spec","developerGuide":"https://api.cleartrace.dev/ai-integration/v1/developer-guide","appFoundation":"https://api.cleartrace.dev/ai-integration/v1/app-foundation","latestKit":"https://api.cleartrace.dev/ai-integration/v1/kit/latest","kitReleases":"https://api.cleartrace.dev/ai-integration/v1/kit/releases","cli":{"contractId":"cleartrace-cli-distribution-v1","version":1,"cliVersion":"0.1.108","packageName":"@cleartrace/cli","nodeVersion":">=20","artifactUrl":"https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz","manifestUrl":"https://api.cleartrace.dev/ai-integration/v1/cli/releases/latest","runner":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace","commands":{"version":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace --version","doctor":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace doctor --solution-id <solutionId>","ticketsList":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace tickets list --solution-id <solutionId> [--project-id <projectId>]","environmentsList":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace environments list --solution-id <solutionId> [--limit <1..50>] [--cursor <nextCursor>]","ticketDetail":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace tickets get --solution-id <solutionId> --ticket-id <ticketId>","ticketHistory":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace tickets history --solution-id <solutionId> --ticket-id <ticketId> [--limit <1..25>] [--offset <0..100000>]","projectChangeState":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace project change-state --solution-id <solutionId> --project-id <projectId>","search":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace search --solution-id <solutionId> --query <text>","planResolve":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace plan resolve --solution-id <solutionId> [--project-id <projectId>] [--ticket-id <ticketId>]","planList":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace plan list --solution-id <solutionId> [--project-id <projectId>] [--status <status>]","planShow":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace plan show --solution-id <solutionId> --plan-id <workingPlanId>","planCreate":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace plan create --solution-id <solutionId> [--project-id <projectId>] --title <text> --objective <text> [--visibility private|team]","planUpdate":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace plan update --solution-id <solutionId> --plan-id <workingPlanId> --expected-version <version> [--title <text>] [--objective <text>] [--status <status>]","planEvent":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace plan event --solution-id <solutionId> --plan-id <workingPlanId> --expected-version <version> --type note|decision|step_added|step_updated|status_changed [--title <text>] [--summary <text>] [--step-id <stepId>] [--step-status <status>] [--status <status>]","projectKit":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace kit --help","assistantAdapters":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace adapters --help","credentialProfile":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace profile --help","solutionInstall":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace solution --help","solutionPreview":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace solution preview --solution-id <solutionId> --project-root <projectId>=<absolute-local-root>","solutionApply":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace solution apply --solution-id <solutionId> --project-root <projectId>=<absolute-local-root> --plan-hash <sha256:...> --approved","changePreview":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace change preview --repo <project-root> --outcome completed","changeSubmit":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace change submit --repo <project-root> --outcome completed --plan-hash <sha256:...> --approved","scanPreview":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace scan preview --repo <project-root>","technologyProfilePreview":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace scan preview --repo <project-root> --domain system_architecture --working-tree --review-profiles","technologyProfileSubmit":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace scan submit --repo <project-root> --domain system_architecture --working-tree --review-profiles --plan-hash <sha256:...> --approved","scanSubmit":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace scan submit --repo <project-root> --plan-hash <sha256:...> --approved","closeoutPreview":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace closeout preview --manifest <closeout-manifest.json> --out <.cleartrace/out/closeout-plan.json>","closeoutSubmit":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace closeout submit --plan <.cleartrace/out/closeout-plan.json> --plan-hash <sha256:...> --approved","architectureDeficits":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace architecture deficits --solution-id <solution-id> [--domain <domain>]","architectureCurrent":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace architecture current --solution-id <solution-id> --domain <domain>","architectureReconcilePreview":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace architecture reconcile-preview --solution-id <solution-id> --request <request.json>","architectureReconcileSubmit":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace architecture reconcile-submit --solution-id <solution-id> --request <request.json> --plan-hash <sha256:...> --approved","taskBegin":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace task begin --session <.cleartrace/out/task-session.json> --repo <project-root>","taskExtend":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace task extend --session <.cleartrace/out/task-session.json> --out <.cleartrace/out/task-session-extended.json> --repo <new-project-root>","taskStatus":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace task status --session <.cleartrace/out/task-session.json>","taskCheckpoint":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace task checkpoint --session <.cleartrace/out/task-session.json> --outcome partial","taskCloseoutPreview":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace task closeout preview --session <.cleartrace/out/task-session.json> --out <.cleartrace/out/closeout-plan.json> --outcome completed","taskCloseoutSubmit":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace task closeout submit --plan <.cleartrace/out/closeout-plan.json> --plan-hash <sha256:...> --approved","taskStart":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace task start --session <.cleartrace/out/task-session.json> --repo <project-root>","taskAddRoot":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace task add-root --session <.cleartrace/out/task-session.json> --out <.cleartrace/out/task-session-extended.json> --repo <new-project-root>","taskPreview":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace task preview --session <.cleartrace/out/task-session.json> --out <.cleartrace/out/closeout-plan.json> --outcome completed","taskSubmit":"npm exec --yes --package=https://api.cleartrace.dev/ai-integration/v1/cli/releases/0.1.108/cleartrace-cli-0.1.108.tgz -- cleartrace task submit --plan <.cleartrace/out/closeout-plan.json> --plan-hash <sha256:...> --approved"},"boundaries":{"apiAndMcp":"download_only","localFilesystemOwner":"cleartrace_cli","approval":"exact_plan_hash_and_approved_flag","fileChangeIdentity":"Immutable capture-scoped IDs bind package/capsule ownership, full source fingerprints, patch digest and file metadata. Identical inputs replay deterministically. Preserve old sessions/evidence and re-preview with the current CLI; never relabel IDs or overwrite accepted records."},"architectureCapabilities":{"componentProfileDeclarations":{"contractId":"cleartrace-component-profile-declarations-v1","version":1,"sourcePath":"architecture/cleartrace-profiles.json","domain":"system_architecture","documentFields":["contractId","version","profiles"],"profileFields":["objectKey","purpose","evidencePaths","interfaces","applicability"],"purposes":["browser_application","mobile_application","service","functions","mcp_server","cli","library","database","control_plane"],"interfaceLimit":500,"interfaceFields":["kind","name","direction","evidencePaths"],"directions":["provides","consumes"],"kinds":{"http":["method","route"],"functions_http":["method","route"],"browser_route":["route"],"mcp_transport":["transport"],"mcp_tool":[],"mcp_resource":[],"mcp_prompt":[],"script_contract":[]},"transports":["stdio","streamable_http","sse"],"applicabilityFields":["section","status","reason","evidencePaths"],"applicabilitySections":["stack","interfaces","versions","run_commands"],"stackRule":"A component no manifest describes may declare section stack with status applicable; its reason names the stack (for example PostgreSQL SQL migrations).","applicabilityStatuses":["applicable","not_applicable","unknown"],"evidenceRule":"Nonempty scanner-selected component-owned relative paths; no cross-component paths or self-evidence. Unknown fields, URLs, credential values and duplicate component keys are rejected. Not-applicable never overrides recorded or unsupported evidence.","runtimeVerified":false,"approval":"existing_exact_profile_preview_hash"},"databaseDeclarations":{"contractId":"cleartrace-database-declarations-v1","version":1,"sourcePath":"architecture/cleartrace-databases.json","domain":"data_model","sinceCliVersion":"0.1.79","documentFields":["contractId","version","databases"],"databaseFields":["name","engine","description","project","sourceOfTruth","baseline","migrations","orm","exclude"],"engines":["postgresql","mysql","mariadb","sqlserver","sqlite","oracle","cockroachdb","other"],"sourcesOfTruth":["migrations","orm","live"],"migrationForms":{"manifest":["manifest","entries","file","appliesTo","value","order","root"],"files":["files","order"]},"ormFields":["kind","schema","role"],"ormKinds":["prisma","typeorm","django","efcore"],"ormRoles":["truth","compare"],"draft":"scan preview --domain data_model prints suggestedDatabaseDeclaration when the file is missing; the developer confirms and commits it.","rule":"Relative paths and globs only; unknown fields, URLs, credentials, absolute and parent paths are refused per database. A duplicate database drops every copy. The ORM in compare role yields drift, not tables."},"cloudDeclarations":{"sinceCliVersion":"0.1.80","domain":"cloud_and_deployment","files":{"environments":{"contractId":"cleartrace-environment-declarations-v1","sourcePath":"architecture/cleartrace-environments.json","fields":["name","description","provider","account","region","deployApproval"],"providers":["azure","aws","gcp","other"]},"services":{"contractId":"cleartrace-service-declarations-v1","sourcePath":"architecture/cleartrace-services.json","fields":["name","kind","description","builtBy","environments","databases","source"],"kinds":["app_service","static_site","function_app","container","database_server","storage","queue","cache","secret_store","network","other"],"bindingFields":["environment","resource","url"],"sourceFields":["iac","scripts","workflows"]},"operations":{"contractId":"cleartrace-operation-declarations-v1","sourcePath":"architecture/cleartrace-operations.json","fields":["name","kind","description","runs","targets","changes","approval"],"kinds":["provision","deploy","migrate","rotate","backup","restore","clone","seed","check","other"],"target":"<environment>:<service>[:<database>]"}},"approvals":["owner","team","none"],"draft":"scan preview --domain cloud_and_deployment prints suggestedEnvironmentDeclaration, suggestedServiceDeclaration and suggestedOperationDeclaration for missing files (marked assumed); the developer confirms and commits them.","gaps":"Every cloud_and_deployment preview prints declarationGaps; show them to the user and offer to fill them.","rule":"Relative paths and globs only; a service url must be https without credentials or a query; unknown fields, secrets, absolute and parent paths are refused per entry; a duplicate name drops every copy; cross-references are reported, not refused."},"flowDeclarations":{"sinceCliVersion":"0.1.82","domain":"data_flow","files":{"flows":{"contractId":"cleartrace-flow-declarations-v1","sourcePath":"architecture/cleartrace-flows.json","fields":["id","name","description","steps","edges","documents"],"fileEntryFields":["file","id","name","description","documents","steps"],"stepFields":["id","name","kind","description","service","database","table","describedBy"],"stepKinds":["source","process","store","review","output","external"],"edgeFields":["from","to","label"],"importedContracts":["reconcilia-data-flow-v1"]},"documentHeader":{"format":"YAML front matter, cleartrace block","fields":["kind","status","about","environments","supersededBy"],"kinds":["plan","design","runbook","decision","current_state","data_flow","spec","note"],"statuses":["draft","active","done","superseded"],"about":"<service|flow|database|project|operation>:<name>"}},"draft":"scan preview --domain data_flow prints suggestedFlowDeclaration when the file is missing and suggestedDocumentHeaders for documents without a valid header (marked assumed); the developer confirms and commits them.","gaps":"Every data_flow preview prints declarationGaps (with cloud_and_deployment's when both are scanned); show them to the user and offer to fill them.","privacy":"Only document titles, headers and commit history are stored, never document text; a flow file's diff only with patch text allowed and when it passes the package privacy rules.","rule":"Relative paths only; unknown fields, secrets, URLs, absolute and parent paths are refused per entry; a duplicate flow id or file drops every copy; edges must name declared steps; references to services and databases are reported, not refused."},"leanCurrentRead":{"query":"includeHistory=false","preservesBaselineChain":true},"readTimings":{"option":"--timings","operations":["current","deficits"],"output":"clientTimings","excludesProcessStartup":true,"serverOnly":false},"interfaceInventory":{"output":"interfaceInventory","exhaustive":false,"recordedDoesNotMeanComplete":true,"legacyProfilesKeepReviewGap":true},"technologyProfileReview":{"contractId":"cleartrace-technology-profile-review-v1","localPreviewField":"stateSnapshots[].technologyProfiles","comparisonOption":"--review-profiles","domain":"system_architecture","authenticatedReadback":true,"runtimeVersionsVerified":false},"architectureLinksVersions":[1,2,3],"qualifiedDeliveryRelationships":true,"scanPurpose":"current_state_not_change_history","previewCollectorDiagnostics":true,"reviewedRelationshipRetirement":{"contractId":"cleartrace-architecture-relationship-reconciliation-v1","requiredScope":"manage:solutions","requiredGrant":"solution_or_workspace","domain":"system_architecture","evidenceReferences":"snapshot:<id>","requiresHostedReadback":true}}},"capabilities":"https://api.cleartrace.dev/ai-integration/v1/capabilities","search":"https://api.cleartrace.dev/ai-integration/v1/search","ticketValidation":"https://api.cleartrace.dev/ai-integration/v1/tickets/validate","changeCapsuleValidation":"https://api.cleartrace.dev/ai-integration/v1/change-capsules/validate","pushWriteSetPreview":"https://api.cleartrace.dev/ai-integration/v1/ingest/write-sets/preview","pushWriteSetSubmission":"https://api.cleartrace.dev/ai-integration/v1/ingest/write-sets","taskCloseoutPreview":"https://api.cleartrace.dev/ai-integration/v1/ingest/task-closeouts/preview","taskCloseoutSubmission":"https://api.cleartrace.dev/ai-integration/v1/ingest/task-closeouts","workspaceDiscoveryPreview":"https://api.cleartrace.dev/ai-integration/v1/workspace-discovery/preview","workspaceDiscoveryApply":"https://api.cleartrace.dev/ai-integration/v1/workspace-discovery/apply","releases":{"contractId":"cleartrace-solution-release-v1","version":4,"evidenceRegistration":{"contractId":"cleartrace-evidence-registration-v1","preview":"/ai-integration/v1/solutions/{solutionId}/evidence/preview","register":"/ai-integration/v1/solutions/{solutionId}/evidence/register","read":"/ai-integration/v1/solutions/{solutionId}/evidence/{evidenceId}","mcpPreview":"cleartrace_preview_solution_evidence","mcpRegister":"cleartrace_register_solution_evidence","mcpRead":"cleartrace_get_solution_evidence","request":{"idempotencyKey":"stable-reviewed-key","items":[{"testRunId":"accepted-test-run-id","evidenceType":"workflow_run | live_build | deployment_verification","uri":"optional public HTTPS provenance URL","commitSha":"optional exact commit","buildIdentity":"optional observed identity"}]},"limits":{"items":20,"requestBytes":32768,"responseBytes":262144,"sourceBytesPerRun":65536,"snapshotBytesPerRun":8192},"scopes":{"previewAndRegister":"write:working_plan","read":"read:working_plan","grant":"matching solution or workspace"},"flow":"Read existing accepted test runs, review their source summaries and optional publisher-declared URL/commit/build metadata. Preview the batch, approve its exact planHash, register {request,planHash,approved:true}, then read every returned evidenceId. Use those canonical IDs as kind:evidence in artifactEvidence, manifest/event references and workflowRunRef/liveBuildRef. A testRunId itself is not an evidenceId. Accepted test-run pushes do not register evidence automatically.","preservation":"Original test runs remain unchanged. Preview binds a full bounded source fingerprint while snapshotting only core metadata; raw payload/provenance bodies, source code and diffs are not copied. Purpose/optional observations are publisher declarations, not automatic extraction or certification. Changed sources before registration need a fresh preview/approval. Accepted retries reuse the original immutable snapshot even if a source later changes; changed request/actor/stored evidence conflicts.","boundary":"No release reservation, event, cancellation, deployment, external URL fetch or automatic retry. Continue an existing preparing release after evidence readback; do not allocate another version. Cancellation of a superseded record needs separate approval."},"recordingModes":{"planned":"Default. Freeze exact deployment artifact digests before following the external project-owned release procedure.","already_deployed":"Explicitly select recordingMode:already_deployed in preview/prepare to record existing deployments without redeploying. Supply actual UTC observedAt on start/finish events and deploymentEvidence for every component on successful finish: projectId, registered workflowRunRef and liveBuildRef (kind:evidence), and liveBuildIdentity. Read-only source archives or rebuilds cannot establish the original deployment artifact digest.","unavailableDigest":"Only already_deployed components may use artifactDigest:null with artifactEvidence:{status:unavailable,reason,references}. Include at least one registered evidence reference. Completion remains possible with artifactEvidenceStatus:incomplete; this is not binary verification. Recording mode and frozen evidence are immutable."},"hashes":{"planHash":"ClearTrace-generated approval hash of the reservation request/version; not a deployment artifact hash.","artifactDigest":"Client-supplied SHA-256 of the actual deployment artifact bytes. Do not substitute a newly built ZIP, source archive, commit hash or planHash for an unavailable original artifact."},"recordExistingDeploymentSteps":["Read the policy, exact registered environment ID, and existing release summaries first. Do not duplicate an accepted record or guess an environment alias.","Collect existing exact commits, successful workflow-run identity/results, live build identity and actual UTC deployment start/finish times. If accepted test runs are not registered evidence, use evidenceRegistration.preview/register with their IDs and reviewed metadata, exact-hash approval and canonical evidence readback. Never relabel testRunId as evidenceId, upload duplicate diffs or repeat existing test-run pushes.","Preview with recordingMode:already_deployed (and a reviewed bump for an established SemVer policy). Present the complete proposed manifest/events, version, missing-digest reasons and exact new planHash for approval. Preparation only reserves a version; it does not create artifact digests.","Before freezing, for each project build a change package from its commit in the preview's previousComponents to the deployed commit: cleartrace change preview|submit --base <previous commit> --head <deployed commit> --no-working-tree. Cite those packages in the manifest; the release then shows every commit it shipped. A project without a previous commit starts where you choose.","After approval, prepare the identical request/hash and freeze the candidate. Use original verifiable artifact digests, or artifactDigest:null plus artifactEvidence:{status:unavailable,reason,references}. Do not create a replacement ZIP/source archive or redeploy to obtain a substitute digest.","Append approved deployment_started with deploymentId,environmentId,targets,references,observedAt (actual UTC start). Append deployment_finished with outcome:succeeded,references,observedAt (actual UTC finish), exact matching observedComponents, and deploymentEvidence for all components. Evidence entries contain projectId,workflowRunRef,liveBuildRef,liveBuildIdentity; both refs have kind:evidence and registered IDs.","Use latest expectedRevision and stable eventId for every approved event. Append release_completed only after all latest attempts succeeded. Read back detail, deployments and events, reporting lifecycle and artifactEvidenceStatus separately. On uncertain writes, read back before idempotent recovery; never repeat the external deployment."],"environments":{"endpoint":"/ai-integration/v1/solutions/{solutionId}/environments","mcpTool":"cleartrace_list_solution_environments","cli":"cleartrace environments list --solution-id <solutionId> [--limit <1..50>] [--cursor <nextCursor>]","readScopes":["read:registry","read:working_plan"],"grant":"matching solution or workspace","registration":{"contractId":"cleartrace-environment-registration-v1","preview":"/ai-integration/v1/solutions/{solutionId}/environments/preview","register":"/ai-integration/v1/solutions/{solutionId}/environments/register","mcpPreview":"cleartrace_preview_solution_environment","mcpRegister":"cleartrace_register_solution_environment","scope":"manage:solutions","bodyLimitBytes":8192,"rule":"Preview {idempotencyKey,name,environmentType}; review server-generated ID and create/reuse action. Register {request,planHash,approved:true} only after exact-hash approval, then read back. No alias guessing, cloud action, release reservation, permission upgrade or browser fallback. Identical retries use the same request/key/hash; conflicts need investigation and a new preview.","localizedSummary":{"en":"Register only reviewed environment metadata; this does not deploy.","es":"Registra solo metadatos del entorno revisados; esto no despliega."}},"paging":"Follow page.nextCursor until page.hasMore=false. Select the exact registered ID by reviewed name/type; prod is not an automatic alias. Empty means no registered environments. Missing targets require the separately approved registration preview/register flow, never an invented ID. A failed read is not an empty inventory."},"boundary":"ClearTrace allocates solution versions and records agent-reported delivery evidence. Project procedures and execution remain outside ClearTrace. No code/diff upload or cloud execution.","range":{"rule":"Freezing a candidate requires, for each project, a cited change package whose commits start at that project's commit in the previous release (the latest release that is not cancelled and has a frozen candidate). Refusal release_range_not_from_previous_release (409) lists projectId, expectedBaseCommitSha, previousVersion, range and rangeStart.","build":"cleartrace change preview|submit --base <previous commit> --head <deployed commit> --no-working-tree, reviewed and approved like any change; the CLI records every commit in between with its message.","exception":"Only a rollback or rewritten history may add rangeException:{reason} (10..500 characters) to that component; the release shows the reason.","abandoned":"Cancel a release that will not ship; until then its frozen commits count as the previous release.","read":"GET /ai-integration/v1/solutions/{solutionId}/releases/{releaseId}/contents shows each project's range, commits, changes and tickets."},"versioning":"One solution-wide version namespace. Policies are reviewed once. Preparation atomically reserves a version; cancelled versions are not reused. Promoting the same frozen candidate creates deployment events, not a new version.","evidence":"Freeze exact component commits and existing package references. Planned releases require artifact digests; already_deployed records allow explicitly unavailable digests with reasons and registered evidence. Ticket context uses immutable ticket revision IDs. Change capsules are contextual references, not immutable code proof. Runtime observations and evidence IDs are reported by the authorized publisher, not independently fetched or certified by ClearTrace.","completion":"Completed means the publisher reported completion with matching component observations and registered evidence. Read artifactEvidenceStatus separately: incomplete explicitly means original binary hashes remain unavailable. Complete artifact evidence means recorded hashes, not independent verification. Completion does not certify that an external procedure, tenant inventory, or every production check was exhaustive.","promotion":"A completed release may start another approved deployment of the same immutable candidate/version to another environment or cohort; its status returns to active. Cancelled releases remain terminal.","localizedSummary":{"en":"For a new release, prepare an approved version and follow your external procedure. For an existing deployment, select already_deployed, record actual times and workflow/live-build evidence, and explicitly explain unavailable binary digests. Do not redeploy, rebuild a substitute hash, copy diffs or treat the ledger as execution authority.","es":"Para una nueva versión, prepara una versión aprobada y sigue tu procedimiento externo. Para un despliegue existente, selecciona already_deployed, registra fechas reales y evidencia del flujo y compilación activa, y explica los hashes binarios no disponibles. No vuelvas a desplegar, generes un hash sustituto, copies diffs ni uses el registro como autorización de ejecución."},"approvals":"Policy and preparation require an exact preview planHash and approved:true. Events require approved:true, expectedRevision and an idempotent eventId. No operation authorizes deployments, SQL execution, Git changes, or additional permissions.","reads":"List and event history are cursor-paged (default 25, maximum 50), with no total-count scan or full-graph fallback. Detail excludes history and diff bodies. Read errors are not empty pages.","scopes":{"read":"read:working_plan","write":"write:working_plan","configure":"manage:solutions","grants":"Solution or workspace grant required; project-only grants cannot read a solution-wide release."},"endpoints":{"policy":"/ai-integration/v1/solutions/{solutionId}/release-policy","policyPreview":"/ai-integration/v1/solutions/{solutionId}/release-policy/preview","preview":"/ai-integration/v1/solutions/{solutionId}/releases/preview","prepare":"/ai-integration/v1/solutions/{solutionId}/releases/prepare","list":"/ai-integration/v1/solutions/{solutionId}/releases","detail":"/ai-integration/v1/solutions/{solutionId}/releases/{releaseId}","events":"/ai-integration/v1/solutions/{solutionId}/releases/{releaseId}/events","deployments":"/ai-integration/v1/solutions/{solutionId}/releases/{releaseId}/deployments","contents":"/ai-integration/v1/solutions/{solutionId}/releases/{releaseId}/contents"}},"packageIngestion":"https://api.cleartrace.dev/ai-integration/v1/ingest/packages","publicSchemas":{"agentSpec":"https://api.cleartrace.dev/ai-integration/v1/schemas/agent-spec.schema.json","projectKit":"https://api.cleartrace.dev/ai-integration/v1/schemas/project-kit.schema.json","projectKitBundle":"https://api.cleartrace.dev/ai-integration/v1/schemas/project-kit-bundle.schema.json","pushEnvelope":"https://api.cleartrace.dev/ai-integration/v1/schemas/push-envelope.schema.json","ticketPushEnvelope":"https://api.cleartrace.dev/ai-integration/v1/schemas/ticket-push-envelope.schema.json","changeCapsulePushEnvelope":"https://api.cleartrace.dev/ai-integration/v1/schemas/change-capsule-push-envelope.schema.json","pushWriteSet":"https://api.cleartrace.dev/ai-integration/v1/schemas/push-write-set.schema.json","taskCloseout":"https://api.cleartrace.dev/ai-integration/v1/schemas/task-closeout.schema.json","changehubPackage":"https://api.cleartrace.dev/ai-integration/v1/schemas/changehub-package.schema.json","workspaceDiscovery":"https://api.cleartrace.dev/ai-integration/v1/schemas/workspace-discovery.schema.json"},"procedure":["Use X-ClearTrace-Api-Key and call /ai-integration/v1/capabilities as the first authenticated ClearTrace request.","For a short request such as \"refresh ClearTrace\" or \"what changed\", follow the matching playbook in the agent spec's firstWrite.userRequests; contract.changes lists what changed since your agent spec version.","If a required capability is false or the target is outside the visible boundary, report the missing capability and stop; never fall back to app.cleartrace.dev, browser automation, or internal /v1 routes.","Read the OpenAPI document, assistant guide, and agent spec after the capability gate.","Use metadata-only workspace discovery for catalog adoption and controlled solution/project metadata updates only when scoped capabilities, owner binding, and grants authorize every create or update operation.","If a project's connectionMode is not selected, report connection_mode_human_configuration_required for evidence activation; still verify or install local project behavior when a project root is accessible.","Use the exact pinned CLI runner published in cli. The API or MCP may download a reviewed behavior-kit bundle; only that local ClearTrace CLI may preview and install it in an active local non-catalog project.","Manage Git remotes, commits, and pushes in the local Git workflow; ClearTrace does not perform those operations.","Capture each changed repository's starting HEAD before edits. After commit or push, the explicit base/head/commit range reconstructs the previous and final file states.","Read project context and change state before creating updates.","Before a baseline or architecture refresh, use the discovered CLI runner with architecture deficits --solution-id <solution-id>, or read the authenticated /ai-integration/v1/solutions/{solutionId}/architecture/scan-deficits endpoint via MCP/API. MCP is optional; the CLI reuses the credential profile. Run only the returned project/domain previews.","Before publishing human ticket assignees or followers, resolve eligible tenant userIds from the project ticket-participant directory or its privacy-safe search; never use an email address or display name as participantId.","Validate package or push payloads before ingestion.","For file-changing work, preview all immutable change packages plus the related typed write set as one task closeout, ask once for its planHash, and submit the returned normalizedCloseout. Use independent package or push routes only for compatible producers or recovery."]}}