@claudexor/schema 1.0.0

package/generated/TaskContract.schema.json

@@ -0,0 +1,501 @@
+{
+  "$ref": "#/definitions/TaskContract",
+  "definitions": {
+    "TaskContract": {
+      "type": "object",
+      "properties": {
+        "schema_version": {
+          "type": "number",
+          "const": 2,
+          "description": "Schema version of the artifact; bumped on breaking ABI changes."
+        },
+        "task_id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Task id this contract belongs to."
+        },
+        "created_at": {
+          "type": "string",
+          "minLength": 1,
+          "description": "When the contract was built."
+        },
+        "repo": {
+          "type": "object",
+          "properties": {
+            "root": {
+              "type": "string",
+              "description": "Absolute path to the project repository root."
+            },
+            "base_ref": {
+              "type": "string",
+              "description": "Git ref the run is based on."
+            },
+            "base_sha": {
+              "type": "string",
+              "description": "Resolved base commit SHA, when known."
+            },
+            "dirty_policy": {
+              "type": "string",
+              "enum": [
+                "refuse",
+                "snapshot"
+              ],
+              "description": "How a dirty working tree is handled when creating an envelope: snapshot captures the dirty state as the base SHA without touching the live tree; refuse fails loudly.",
+              "default": "refuse"
+            }
+          },
+          "required": [
+            "root",
+            "base_ref"
+          ],
+          "additionalProperties": false,
+          "description": "Repository the run operates on and how a dirty tree is handled."
+        },
+        "mode": {
+          "type": "object",
+          "properties": {
+            "kind": {
+              "type": "string",
+              "enum": [
+                "ask",
+                "plan",
+                "audit",
+                "agent",
+                "orchestrate"
+              ],
+              "description": "Canonical run mode: ask, plan, and audit are read-only; agent writes; orchestrate is the autonomous coordinator intent. Engine strategies (race, attempts, swarm, create) are flags on a mode, not modes."
+            }
+          },
+          "required": [
+            "kind"
+          ],
+          "additionalProperties": false,
+          "description": "Canonical run mode for this task."
+        },
+        "user_intent": {
+          "type": "object",
+          "properties": {
+            "raw": {
+              "type": "string",
+              "description": "The user's original prompt, verbatim."
+            },
+            "normalized": {
+              "type": "string",
+              "description": "Optional normalized restatement of the prompt."
+            }
+          },
+          "required": [
+            "raw"
+          ],
+          "additionalProperties": false,
+          "description": "The user's request this run is held to."
+        },
+        "spec": {
+          "type": "object",
+          "properties": {
+            "id": {
+              "type": "string",
+              "minLength": 1,
+              "description": "SpecPack id."
+            },
+            "hash": {
+              "type": "string",
+              "description": "Content hash of the frozen SpecPack."
+            },
+            "path": {
+              "type": "string",
+              "description": "On-disk path of the SpecPack artifact."
+            }
+          },
+          "additionalProperties": false,
+          "description": "Reference to the frozen SpecPack this contract was derived from, if any."
+        },
+        "success_criteria": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": {
+                "type": "string",
+                "minLength": 1,
+                "description": "Criterion id."
+              },
+              "text": {
+                "type": "string",
+                "description": "Human-readable statement of what must hold for the run to succeed."
+              },
+              "required": {
+                "type": "boolean",
+                "default": true,
+                "description": "Whether this criterion is required (vs advisory)."
+              }
+            },
+            "required": [
+              "id",
+              "text"
+            ],
+            "additionalProperties": false,
+            "description": "A single success criterion the run is held to."
+          },
+          "default": [],
+          "description": "Criteria the run must satisfy to succeed."
+        },
+        "non_goals": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": [],
+          "description": "Explicitly out-of-scope outcomes."
+        },
+        "forbidden_approaches": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": [],
+          "description": "Approaches the run must not take."
+        },
+        "decided_tradeoffs": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": [],
+          "description": "Tradeoffs already decided; reviewers must not re-litigate them."
+        },
+        "task_graph": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "nodes": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "properties": {
+                      "id": {
+                        "type": "string",
+                        "minLength": 1,
+                        "description": "Task node id."
+                      },
+                      "title": {
+                        "type": "string",
+                        "default": "",
+                        "description": "Human-readable task title."
+                      },
+                      "depends_on": {
+                        "type": "array",
+                        "items": {
+                          "$ref": "#/definitions/TaskContract/properties/spec/properties/id"
+                        },
+                        "default": [],
+                        "description": "Ids of tasks this node depends on (graph edges)."
+                      }
+                    },
+                    "required": [
+                      "id"
+                    ],
+                    "additionalProperties": false,
+                    "description": "One node of the spec-derived task graph; edges are depends_on."
+                  },
+                  "default": [],
+                  "description": "Task nodes of the graph."
+                },
+                "order": {
+                  "type": "array",
+                  "items": {
+                    "$ref": "#/definitions/TaskContract/properties/spec/properties/id"
+                  },
+                  "default": [],
+                  "description": "Topological execution order (node ids); empty when there are no tasks."
+                }
+              },
+              "additionalProperties": false,
+              "description": "A topologically-ordered task graph built from a frozen SpecPack's tasks."
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Spec-derived task graph; null until a frozen SpecPack with tasks is resolved.",
+          "default": null
+        },
+        "constraints": {
+          "type": "object",
+          "properties": {
+            "protected_paths": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "default": [],
+              "description": "Spec/config-owned globs whose changes escalate risk to a human-approval gate; cannot be suppressed by per-run protected-path approvals."
+            },
+            "auto_protected_paths": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "default": [],
+              "description": "Engine-derived gate/test path protections; per-run approvals can narrow only this set."
+            },
+            "protected_path_approvals": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "path": {
+                    "type": "string",
+                    "minLength": 1,
+                    "pattern": "\\S",
+                    "description": "Glob approved by the operator/user for this run; consumed only by the auto-protected gate/test path policy, not by built-in critical-path gates."
+                  },
+                  "reason": {
+                    "type": "string",
+                    "minLength": 1,
+                    "pattern": "\\S",
+                    "description": "Optional human-readable reason for the approval."
+                  }
+                },
+                "required": [
+                  "path"
+                ],
+                "additionalProperties": false,
+                "description": "Per-run typed operator approval allowing changes under an auto-protected gate/test path."
+              },
+              "default": [],
+              "description": "Per-run typed approvals for protected gate/test path changes, produced by explicit surfaces and consumed by policy."
+            }
+          },
+          "additionalProperties": false,
+          "description": "Path-protection constraints applied to a run.",
+          "default": {}
+        },
+        "tests": {
+          "type": "object",
+          "properties": {
+            "commands": {
+              "type": "array",
+              "items": {
+                "type": "object",
+                "properties": {
+                  "id": {
+                    "type": "string",
+                    "minLength": 1,
+                    "description": "Test command id."
+                  },
+                  "command": {
+                    "type": "string",
+                    "description": "Shell command executed as a deterministic gate."
+                  },
+                  "required": {
+                    "type": "boolean",
+                    "default": true,
+                    "description": "Whether this test must pass (vs advisory)."
+                  }
+                },
+                "required": [
+                  "id",
+                  "command"
+                ],
+                "additionalProperties": false,
+                "description": "A deterministic test command used as a verification gate."
+              },
+              "default": [],
+              "description": "Deterministic test commands configured as gates."
+            }
+          },
+          "additionalProperties": false,
+          "default": {
+            "commands": []
+          },
+          "description": "Deterministic test gates for the run."
+        },
+        "access": {
+          "type": "object",
+          "properties": {
+            "requested_profile": {
+              "type": "string",
+              "enum": [
+                "readonly",
+                "workspace_write",
+                "full",
+                "external_sandbox_full",
+                "inherit_native"
+              ],
+              "description": "Access profile the caller requested.",
+              "default": "workspace_write"
+            },
+            "effective_profile": {
+              "$ref": "#/definitions/TaskContract/properties/access/properties/requested_profile",
+              "default": "workspace_write",
+              "description": "Access profile actually enforced by the engine (mode/trust clamps applied; never client-supplied)."
+            }
+          },
+          "additionalProperties": false,
+          "default": {
+            "requested_profile": "workspace_write",
+            "effective_profile": "workspace_write"
+          },
+          "description": "Requested vs engine-enforced access profile."
+        },
+        "external_context": {
+          "type": "object",
+          "properties": {
+            "policy": {
+              "type": "string",
+              "enum": [
+                "off",
+                "auto",
+                "cached",
+                "live"
+              ],
+              "description": "Requested external web/context policy.",
+              "default": "auto"
+            },
+            "web_required": {
+              "type": "boolean",
+              "default": false,
+              "description": "Whether the task requires live web evidence."
+            },
+            "effective_mode": {
+              "$ref": "#/definitions/TaskContract/properties/external_context/properties/policy",
+              "default": "auto",
+              "description": "Policy the selected route actually executes (disclosed upgrades, e.g. cached to live)."
+            }
+          },
+          "additionalProperties": false,
+          "default": {
+            "policy": "auto",
+            "web_required": false,
+            "effective_mode": "auto"
+          },
+          "description": "External web/context policy for the run."
+        },
+        "tool_permission_policy": {
+          "type": "object",
+          "properties": {
+            "web": {
+              "$ref": "#/definitions/TaskContract/properties/external_context/properties/policy",
+              "default": "auto",
+              "description": "Web policy forwarded to tool permissioning."
+            },
+            "allow": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "default": [],
+              "description": "Tool names explicitly allowed."
+            },
+            "deny": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              },
+              "default": [],
+              "description": "Tool names explicitly denied."
+            }
+          },
+          "additionalProperties": false,
+          "default": {
+            "web": "auto",
+            "allow": [],
+            "deny": []
+          },
+          "description": "Tool permission policy passed to harnesses that support allow/deny lists."
+        },
+        "budget": {
+          "type": "object",
+          "properties": {
+            "portfolio": {
+              "type": "string",
+              "enum": [
+                "daily-rich",
+                "balanced",
+                "cheapest",
+                "strongest",
+                "burn",
+                "subscription-first",
+                "api-overflow",
+                "conserve-claude",
+                "conserve-codex"
+              ],
+              "description": "Budget portfolio weighting the harness router's quality/cost/latency and subscription-vs-API preferences (e.g. cheapest minimizes spend, burn maximizes quality, conserve-* deprioritizes one vendor).",
+              "default": "subscription-first"
+            },
+            "max_usd": {
+              "type": [
+                "number",
+                "null"
+              ],
+              "default": null,
+              "description": "Hard USD cap for the run; null = no cap."
+            }
+          },
+          "additionalProperties": false,
+          "default": {},
+          "description": "Budget portfolio and spend cap for the run."
+        },
+        "routing_models": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          },
+          "default": {},
+          "description": "Resolved harness-scoped model map for this run (harness id to model id); empty means every route uses its per-harness settings default."
+        },
+        "convergence": {
+          "type": "object",
+          "properties": {
+            "require_tests_pass": {
+              "type": "boolean",
+              "default": true,
+              "description": "Require all configured test commands to pass before convergence."
+            },
+            "require_no_accepted_block_open": {
+              "type": "boolean",
+              "default": true,
+              "description": "Block convergence while an accepted BLOCK review finding is still open."
+            },
+            "require_no_accepted_fix_first_open": {
+              "type": "boolean",
+              "default": true,
+              "description": "Block convergence while an accepted FIX_FIRST review finding is still open."
+            },
+            "require_final_cross_family_clean_review": {
+              "type": "boolean",
+              "default": true,
+              "description": "Require a final clean review from a different provider family before convergence."
+            },
+            "require_final_diff_stable_after_review": {
+              "type": "boolean",
+              "default": true,
+              "description": "Require the diff to be unchanged after the final review (a mutated diff makes the review stale)."
+            },
+            "require_no_accepted_needs_human_open": {
+              "type": "boolean",
+              "default": true,
+              "description": "Block convergence while an accepted NEEDS_HUMAN escalation is still open."
+            }
+          },
+          "additionalProperties": false,
+          "description": "Predicate deciding when an until-clean/convergence run may stop as successful.",
+          "default": {}
+        }
+      },
+      "required": [
+        "schema_version",
+        "task_id",
+        "created_at",
+        "repo",
+        "mode",
+        "user_intent"
+      ],
+      "additionalProperties": false,
+      "description": "Immutable contract describing a single run; built once, hashed, never mutated."
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}

package/generated/Thread.schema.json

@@ -0,0 +1,176 @@
+{
+  "$ref": "#/definitions/Thread",
+  "definitions": {
+    "Thread": {
+      "type": "object",
+      "properties": {
+        "schema_version": {
+          "type": "number",
+          "const": 2,
+          "description": "Schema version of the artifact; bumped on breaking ABI changes."
+        },
+        "id": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Thread id."
+        },
+        "created_at": {
+          "type": "string",
+          "minLength": 1,
+          "description": "When the thread was created."
+        },
+        "updated_at": {
+          "type": "string",
+          "minLength": 1,
+          "description": "When the thread was last updated."
+        },
+        "repo": {
+          "anyOf": [
+            {
+              "type": "object",
+              "properties": {
+                "root": {
+                  "type": "string",
+                  "description": "Absolute path of the project root."
+                },
+                "base_ref": {
+                  "type": "string",
+                  "description": "Git ref the thread works against."
+                }
+              },
+              "required": [
+                "root",
+                "base_ref"
+              ],
+              "additionalProperties": false
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "Project the thread is anchored to; null for a no-project Ask thread."
+        },
+        "title": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "default": null,
+          "description": "Thread title; null until set."
+        },
+        "mode": {
+          "type": "string",
+          "enum": [
+            "ask",
+            "plan",
+            "audit",
+            "agent",
+            "orchestrate"
+          ],
+          "description": "Default mode for new turns; individual turns may override.",
+          "default": "agent"
+        },
+        "auth_preference": {
+          "type": "string",
+          "enum": [
+            "subscription",
+            "api_key",
+            "auto"
+          ],
+          "description": "Preferred auth route: subscription (native/OAuth session), api_key (a stored API key), or auto (engine picks subscription-first with policy fallback). A preference, not a secret.",
+          "default": "auto"
+        },
+        "primary_harness": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "default": null,
+          "description": "Sticky primary harness for the thread (re-routable); an ordering bias, not a privileged role."
+        },
+        "eligible_harnesses": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "default": [],
+          "description": "Sticky eligible harness pool for the thread (races run one candidate per pool member); empty = the engine auto-pools doctor-ok harnesses."
+        },
+        "workspace": {
+          "type": "object",
+          "properties": {
+            "mode": {
+              "type": "string",
+              "enum": [
+                "in_place",
+                "isolated"
+              ],
+              "description": "Per-thread workspace mode: in_place mutates the live project tree directly (the default); isolated keeps a persistent git worktree per thread that apply merges into the project.",
+              "default": "in_place"
+            },
+            "worktree_path": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "default": null,
+              "description": "Persistent worktree path; set lazily on the first write turn of an isolated thread."
+            },
+            "base_sha": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "default": null,
+              "description": "Snapshot SHA the isolated worktree (or last apply) is based on."
+            }
+          },
+          "additionalProperties": false,
+          "description": "How the thread's turns touch files (in-place live tree vs isolated worktree).",
+          "default": {}
+        },
+        "run_ids": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1,
+            "description": "Non-empty identifier string."
+          },
+          "default": [],
+          "description": "Ordered run lineage (each run is a turn move)."
+        },
+        "head_run_id": {
+          "anyOf": [
+            {
+              "$ref": "#/definitions/Thread/properties/run_ids/items"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "description": "Most recent run of the thread; null before the first turn runs.",
+          "default": null
+        },
+        "state": {
+          "type": "string",
+          "enum": [
+            "active",
+            "closed"
+          ],
+          "description": "Thread lifecycle state: active or explicitly closed (archived). Blocked is a live projection, not a thread state.",
+          "default": "active"
+        }
+      },
+      "required": [
+        "schema_version",
+        "id",
+        "created_at",
+        "updated_at"
+      ],
+      "additionalProperties": false,
+      "description": "The Claudexor-owned conversation about a project; runs are turns inside it. SSOT for lineage; vendor sessions are caches."
+    }
+  },
+  "$schema": "http://json-schema.org/draft-07/schema#"
+}