Diagnostics and remediation / JSON Schema
Workspai Artifact Remediation Plan
Defines the versioned artifact remediation plan v1 boundary used by Workspai and its consumers.
- Schema version
artifact-remediation-plan-v1- Contract path
contracts/artifact-remediation-plan.v1.json- Publication
- json-schema
- Defined fields
- 76
- Artifact bindings
- 1
Why this contract exists
Architecture role
Defines a versioned interoperability boundary used by Workspai and contract-aware consumers.
Consumption boundary
- • Workspai CLI
- • Contract-aware integrations
Related commands
Commands are linked only when the runtime contract identifies a direct production relationship. Supporting contracts may be consumed without having a single producer command.
Produced artifacts
These durable files are emitted by registered commands and validated against this contract.
| Artifact path | Schema | Producer |
|---|---|---|
| .workspai/reports/artifact-remediation-plan-last-run.json | artifact-remediation-plan-v1 | workspai workspace remediation-plan |
Field reference
Every declared schema property or published capability path is listed here. Required means the contract declares or publishes that field at the shown boundary.
| Field path | Type | Required | Meaning | Constraints |
|---|---|---|---|---|
| $defs.action.artifactKind | string | Yes | Defines the artifactkind value at this contract boundary. | — |
| $defs.action.blocker | string | Yes | Defines the blocker value at this contract boundary. | — |
| $defs.action.cardId | string | Yes | Defines the cardid value at this contract boundary. | — |
| $defs.action.causalKey | string | Yes | Defines the causalkey value at this contract boundary. | minLength: 1 |
| $defs.action.command | string | No | Defines the command value at this contract boundary. | — |
| $defs.action.cwd | enum | Yes | Defines the cwd value at this contract boundary. | enum: workspace, project |
| $defs.action.dependsOn | array | No | Defines the dependson value at this contract boundary. | — |
| $defs.action.files | array | Yes | Defines the files value at this contract boundary. | — |
| $defs.action.findingId | string | Yes | Defines the findingid value at this contract boundary. | minLength: 1 |
| $defs.action.findingStatus | enum | Yes | Defines the findingstatus value at this contract boundary. | enum: blocking, advisory, informational, unknown |
| $defs.action.id | string | Yes | Defines the id value at this contract boundary. | — |
| $defs.action.invocation | reference | No | Defines the invocation value at this contract boundary. | ref: #/$defs/commandInvocation |
| $defs.action.mode | enum | Yes | Defines the mode value at this contract boundary. | enum: edit-file, run-command, refresh-evidence, verify-before-fix, manual-guidance |
| $defs.action.notes | array | Yes | Defines the notes value at this contract boundary. | — |
| $defs.action.operation | reference | No | Defines the operation value at this contract boundary. | ref: #/$defs/operation |
| $defs.action.order | integer | Yes | Defines the order value at this contract boundary. | minimum: 0 |
| $defs.action.phase | string | Yes | Defines the phase value at this contract boundary. | — |
| $defs.action.projectName | string | No | Defines the projectname value at this contract boundary. | minLength: 1 |
| $defs.action.projectPath | string | No | Defines the projectpath value at this contract boundary. | minLength: 1 |
| $defs.action.requiresApproval | boolean | Yes | Defines the requiresapproval value at this contract boundary. | — |
| $defs.action.risk | enum | Yes | Defines the risk value at this contract boundary. | enum: safe, guarded, invasive |
| $defs.action.rollback | object | Yes | Defines the rollback value at this contract boundary. | additionalProperties: false |
| $defs.action.rollback.available | boolean | Yes | Defines the available value at this contract boundary. | — |
| $defs.action.rollback.strategy | enum | Yes | Defines the strategy value at this contract boundary. | enum: idempotent, manual, none |
| $defs.action.scope | enum | Yes | Defines the scope value at this contract boundary. | enum: workspace, project |
| $defs.action.sourceStepId | string | No | Defines the sourcestepid value at this contract boundary. | minLength: 1 |
| $defs.action.status | enum | Yes | Defines the status value at this contract boundary. | enum: ready, review-required, blocked, guidance-only |
| $defs.action.strategy | array | No | Defines the strategy value at this contract boundary. | — |
| $defs.action.summary | string | Yes | Defines the summary value at this contract boundary. | — |
| $defs.action.title | string | Yes | Defines the title value at this contract boundary. | — |
| $defs.action.transaction | reference | No | Defines the transaction value at this contract boundary. | ref: #/$defs/dependencyRepairTransaction |
| $defs.action.verifyCommand | string | Yes | Defines the verifycommand value at this contract boundary. | — |
| $defs.commandInvocation.args | array | Yes | Defines the args value at this contract boundary. | — |
| $defs.commandInvocation.cwd | string | Yes | Defines the cwd value at this contract boundary. | minLength: 1 |
| $defs.commandInvocation.executable | string | Yes | Defines the executable value at this contract boundary. | minLength: 1 |
| $defs.dependencyRepairTransaction.completion | object | Yes | Defines the completion value at this contract boundary. | additionalProperties: false |
| $defs.dependencyRepairTransaction.completion.auditClean | boolean | No | Defines the auditclean value at this contract boundary. | const: true |
| $defs.dependencyRepairTransaction.completion.canonicalVerificationRequired | boolean | Yes | Defines the canonicalverificationrequired value at this contract boundary. | const: true |
| $defs.dependencyRepairTransaction.completion.declaredBuildPass | boolean | Yes | Defines the declaredbuildpass value at this contract boundary. | const: true |
| $defs.dependencyRepairTransaction.completion.declaredTestsPass | boolean | Yes | Defines the declaredtestspass value at this contract boundary. | const: true |
| $defs.dependencyRepairTransaction.completion.installedTreePresent | boolean | No | Defines the installedtreepresent value at this contract boundary. | const: true |
| $defs.dependencyRepairTransaction.completion.manifestLockConsistent | boolean | Yes | Defines the manifestlockconsistent value at this contract boundary. | const: true |
| $defs.dependencyRepairTransaction.ecosystem | string | Yes | Defines the ecosystem value at this contract boundary. | minLength: 1 |
| $defs.dependencyRepairTransaction.kind | enum | Yes | Defines the kind value at this contract boundary. | enum: dependency-security, dependency-materialization |
| $defs.dependencyRepairTransaction.observableState | enum | No | Defines the observablestate value at this contract boundary. | enum: runtime-dependency-tree |
| $defs.dependencyRepairTransaction.projectPath | string | Yes | Defines the projectpath value at this contract boundary. | minLength: 1 |
| $defs.dependencyRepairTransaction.requiredStages | array | Yes | Defines the requiredstages value at this contract boundary. | — |
| $defs.dependencyRepairTransaction.schemaVersion | string | Yes | Defines the schemaversion value at this contract boundary. | const: "workspai.doctor-dependency-repair-transaction.v1" |
| $defs.dependencyRepairTransaction.sourceMutationRequired | boolean | No | Defines the sourcemutationrequired value at this contract boundary. | — |
| $defs.dependencyRepairTransaction.state | string | Yes | Defines the state value at this contract boundary. | const: "planned" |
| $defs.repairStrategyStage.continueWhen | enum | Yes | Defines the continuewhen value at this contract boundary. | enum: always, previous-passed, blocker-remains, manual-decision |
| $defs.repairStrategyStage.description | string | Yes | Defines the description value at this contract boundary. | minLength: 1 |
| $defs.repairStrategyStage.id | string | Yes | Defines the id value at this contract boundary. | minLength: 1 |
| $defs.repairStrategyStage.invocation | reference | No | Defines the invocation value at this contract boundary. | ref: #/$defs/commandInvocation |
| $defs.repairStrategyStage.kind | enum | Yes | Defines the kind value at this contract boundary. | enum: diagnose, safe-fix, targeted-upgrade, verify, exception-review |
| $defs.repairStrategyStage.risk | enum | Yes | Defines the risk value at this contract boundary. | enum: safe, guarded, invasive |
| $defs.riskSummary.guarded | integer | Yes | Defines the guarded value at this contract boundary. | minimum: 0 |
| $defs.riskSummary.invasive | integer | Yes | Defines the invasive value at this contract boundary. | minimum: 0 |
| $defs.riskSummary.safe | integer | Yes | Defines the safe value at this contract boundary. | minimum: 0 |
| actions | array | Yes | Defines the actions value at this contract boundary. | — |
| generatedAt | string | Yes | Defines the generatedat value at this contract boundary. | — |
| schemaVersion | string | Yes | Defines the schemaversion value at this contract boundary. | const: "artifact-remediation-plan-v1" |
| source | object | Yes | Defines the source value at this contract boundary. | additionalProperties: false |
| source.ciMode | boolean | Yes | Defines the cimode value at this contract boundary. | — |
| source.command | string | Yes | Defines the command value at this contract boundary. | const: "workspace remediation-plan" |
| source.includeAbsolutePaths | boolean | Yes | Defines the includeabsolutepaths value at this contract boundary. | — |
| source.reportsDir | string | Yes | Defines the reportsdir value at this contract boundary. | — |
| summary | object | Yes | Defines the summary value at this contract boundary. | additionalProperties: false |
| summary.artifactsScanned | integer | Yes | Defines the artifactsscanned value at this contract boundary. | minimum: 0 |
| summary.cardsCovered | integer | Yes | Defines the cardscovered value at this contract boundary. | minimum: 0 |
| summary.executableActions | integer | Yes | Defines the executableactions value at this contract boundary. | minimum: 0 |
| summary.risk | reference | Yes | Defines the risk value at this contract boundary. | ref: #/$defs/riskSummary |
| summary.totalActions | integer | Yes | Defines the totalactions value at this contract boundary. | minimum: 0 |
| workspace | object | Yes | Defines the workspace value at this contract boundary. | additionalProperties: false |
| workspace.name | string | Yes | Defines the name value at this contract boundary. | — |
| workspace.path | string | No | Defines the path value at this contract boundary. | — |
Canonical machine-readable definition
The raw synchronized contract remains authoritative. The educational sections above are projections of this definition.
Show raw JSON
{
"$schema": "https://json-schema.org/draft/2020-12/schema",
"$id": "https://workspai.dev/contracts/artifact-remediation-plan.v1.json",
"title": "Workspai Artifact Remediation Plan",
"type": "object",
"additionalProperties": false,
"required": [
"schemaVersion",
"generatedAt",
"workspace",
"source",
"summary",
"actions"
],
"properties": {
"schemaVersion": {
"const": "artifact-remediation-plan-v1"
},
"generatedAt": {
"type": "string"
},
"workspace": {
"type": "object",
"additionalProperties": false,
"required": [
"name"
],
"properties": {
"name": {
"type": "string"
},
"path": {
"type": "string"
}
}
},
"source": {
"type": "object",
"additionalProperties": false,
"required": [
"command",
"reportsDir",
"includeAbsolutePaths",
"ciMode"
],
"properties": {
"command": {
"const": "workspace remediation-plan"
},
"reportsDir": {
"type": "string"
},
"includeAbsolutePaths": {
"type": "boolean"
},
"ciMode": {
"type": "boolean"
}
}
},
"summary": {
"type": "object",
"additionalProperties": false,
"required": [
"artifactsScanned",
"cardsCovered",
"totalActions",
"executableActions",
"risk"
],
"properties": {
"artifactsScanned": {
"type": "integer",
"minimum": 0
},
"cardsCovered": {
"type": "integer",
"minimum": 0
},
"totalActions": {
"type": "integer",
"minimum": 0
},
"executableActions": {
"type": "integer",
"minimum": 0
},
"risk": {
"$ref": "#/$defs/riskSummary"
}
}
},
"actions": {
"type": "array",
"items": {
"$ref": "#/$defs/action"
}
}
},
"$defs": {
"riskSummary": {
"type": "object",
"additionalProperties": false,
"required": [
"safe",
"guarded",
"invasive"
],
"properties": {
"safe": {
"type": "integer",
"minimum": 0
},
"guarded": {
"type": "integer",
"minimum": 0
},
"invasive": {
"type": "integer",
"minimum": 0
}
}
},
"operation": {
"oneOf": [
{
"type": "object",
"additionalProperties": false,
"required": [
"type",
"path",
"content",
"overwrite"
],
"properties": {
"type": {
"const": "file-create"
},
"path": {
"type": "string"
},
"content": {
"type": "string"
},
"overwrite": {
"const": false
}
}
},
{
"type": "object",
"additionalProperties": false,
"required": [
"type",
"path",
"lines",
"ensureNewline"
],
"properties": {
"type": {
"const": "file-append"
},
"path": {
"type": "string"
},
"lines": {
"type": "array",
"items": {
"type": "string"
}
},
"ensureNewline": {
"type": "boolean"
}
}
},
{
"type": "object",
"additionalProperties": false,
"required": [
"type",
"sourcePath",
"path",
"overwrite"
],
"properties": {
"type": {
"const": "file-copy"
},
"sourcePath": {
"type": "string"
},
"path": {
"type": "string"
},
"overwrite": {
"const": false
}
}
},
{
"type": "object",
"additionalProperties": false,
"required": [
"type",
"path",
"scriptName",
"scriptValue"
],
"properties": {
"type": {
"const": "package-json-script"
},
"path": {
"type": "string"
},
"scriptName": {
"type": "string"
},
"scriptValue": {
"type": "string"
}
}
},
{
"type": "object",
"additionalProperties": false,
"required": [
"type",
"path",
"edits"
],
"properties": {
"type": {
"const": "json-edit"
},
"path": {
"type": "string"
},
"edits": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"pointer",
"value"
],
"properties": {
"pointer": {
"type": "string"
},
"value": {
"type": [
"string",
"number",
"boolean",
"null"
]
}
}
}
}
}
},
{
"type": "object",
"additionalProperties": false,
"required": [
"type",
"path",
"keys"
],
"properties": {
"type": {
"const": "env-key-add"
},
"path": {
"type": "string"
},
"keys": {
"type": "array",
"items": {
"type": "object",
"additionalProperties": false,
"required": [
"name",
"value"
],
"properties": {
"name": {
"type": "string"
},
"value": {
"type": "string"
},
"comment": {
"type": "string"
}
}
}
}
}
},
{
"type": "object",
"additionalProperties": false,
"required": [
"type",
"path",
"target",
"command",
"phony"
],
"properties": {
"type": {
"const": "makefile-target"
},
"path": {
"type": "string"
},
"target": {
"type": "string"
},
"command": {
"type": "string"
},
"phony": {
"type": "boolean"
}
}
},
{
"type": "object",
"additionalProperties": false,
"required": [
"type",
"command",
"cwd"
],
"properties": {
"type": {
"const": "run-command"
},
"command": {
"type": "string"
},
"cwd": {
"enum": [
"workspace",
"project"
]
}
}
}
]
},
"commandInvocation": {
"type": "object",
"additionalProperties": false,
"required": [
"cwd",
"executable",
"args"
],
"properties": {
"cwd": {
"type": "string",
"minLength": 1
},
"executable": {
"type": "string",
"minLength": 1
},
"args": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"repairStrategyStage": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"kind",
"description",
"risk",
"continueWhen"
],
"properties": {
"id": {
"type": "string",
"minLength": 1
},
"kind": {
"enum": [
"diagnose",
"safe-fix",
"targeted-upgrade",
"verify",
"exception-review"
]
},
"description": {
"type": "string",
"minLength": 1
},
"risk": {
"enum": [
"safe",
"guarded",
"invasive"
]
},
"invocation": {
"$ref": "#/$defs/commandInvocation"
},
"continueWhen": {
"enum": [
"always",
"previous-passed",
"blocker-remains",
"manual-decision"
]
}
}
},
"dependencyRepairTransaction": {
"type": "object",
"additionalProperties": false,
"required": [
"schemaVersion",
"kind",
"state",
"projectPath",
"ecosystem",
"requiredStages",
"completion"
],
"properties": {
"schemaVersion": {
"const": "workspai.doctor-dependency-repair-transaction.v1"
},
"kind": {
"enum": [
"dependency-security",
"dependency-materialization"
]
},
"state": {
"const": "planned"
},
"projectPath": {
"type": "string",
"minLength": 1
},
"ecosystem": {
"type": "string",
"minLength": 1
},
"sourceMutationRequired": {
"type": "boolean"
},
"observableState": {
"enum": [
"runtime-dependency-tree"
]
},
"requiredStages": {
"type": "array",
"items": {
"enum": [
"reconcile",
"audit",
"test",
"build"
]
},
"uniqueItems": true
},
"completion": {
"type": "object",
"additionalProperties": false,
"required": [
"manifestLockConsistent",
"declaredTestsPass",
"declaredBuildPass",
"canonicalVerificationRequired"
],
"properties": {
"manifestLockConsistent": {
"const": true
},
"auditClean": {
"const": true
},
"installedTreePresent": {
"const": true
},
"declaredTestsPass": {
"const": true
},
"declaredBuildPass": {
"const": true
},
"canonicalVerificationRequired": {
"const": true
}
}
}
},
"allOf": [
{
"if": {
"properties": {
"kind": {
"const": "dependency-security"
}
}
},
"then": {
"properties": {
"completion": {
"type": "object",
"properties": {
"auditClean": {
"const": true
}
},
"required": [
"auditClean"
]
}
}
}
},
{
"if": {
"properties": {
"kind": {
"const": "dependency-materialization"
}
}
},
"then": {
"required": [
"sourceMutationRequired",
"observableState"
],
"properties": {
"sourceMutationRequired": {
"const": false
},
"observableState": {
"const": "runtime-dependency-tree"
},
"completion": {
"type": "object",
"properties": {
"installedTreePresent": {
"const": true
}
},
"required": [
"installedTreePresent"
]
}
}
}
}
]
},
"action": {
"type": "object",
"additionalProperties": false,
"required": [
"id",
"artifactKind",
"cardId",
"title",
"order",
"phase",
"scope",
"findingId",
"findingStatus",
"causalKey",
"status",
"mode",
"risk",
"requiresApproval",
"blocker",
"summary",
"verifyCommand",
"cwd",
"files",
"rollback",
"notes"
],
"properties": {
"id": {
"type": "string"
},
"artifactKind": {
"type": "string"
},
"cardId": {
"type": "string"
},
"title": {
"type": "string"
},
"order": {
"type": "integer",
"minimum": 0
},
"phase": {
"type": "string"
},
"scope": {
"enum": [
"workspace",
"project"
]
},
"projectName": {
"type": "string",
"minLength": 1
},
"projectPath": {
"type": "string",
"minLength": 1
},
"sourceStepId": {
"type": "string",
"minLength": 1
},
"findingId": {
"type": "string",
"minLength": 1
},
"findingStatus": {
"enum": [
"blocking",
"advisory",
"informational",
"unknown"
]
},
"causalKey": {
"type": "string",
"minLength": 1
},
"dependsOn": {
"type": "array",
"items": {
"type": "string",
"minLength": 1
}
},
"strategy": {
"type": "array",
"items": {
"$ref": "#/$defs/repairStrategyStage"
}
},
"transaction": {
"$ref": "#/$defs/dependencyRepairTransaction"
},
"status": {
"enum": [
"ready",
"review-required",
"blocked",
"guidance-only"
]
},
"mode": {
"enum": [
"edit-file",
"run-command",
"refresh-evidence",
"verify-before-fix",
"manual-guidance"
]
},
"risk": {
"enum": [
"safe",
"guarded",
"invasive"
]
},
"requiresApproval": {
"type": "boolean"
},
"blocker": {
"type": "string"
},
"summary": {
"type": "string"
},
"command": {
"type": "string"
},
"invocation": {
"$ref": "#/$defs/commandInvocation"
},
"verifyCommand": {
"type": "string"
},
"cwd": {
"enum": [
"workspace",
"project"
]
},
"files": {
"type": "array",
"items": {
"type": "string"
}
},
"operation": {
"$ref": "#/$defs/operation"
},
"rollback": {
"type": "object",
"additionalProperties": false,
"required": [
"available",
"strategy"
],
"properties": {
"available": {
"type": "boolean"
},
"strategy": {
"enum": [
"idempotent",
"manual",
"none"
]
}
}
},
"notes": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
}
}