@geraldmaron/construct 1.4.0 → 1.4.2

package/schemas/specialist-trace.schema.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://construct.dev/schemas/specialist-trace.schema.json",
+  "title": "SpecialistTrace",
+  "description": "One specialist execution trace for the governed improvement loop (construct-6zga.1.7). Captures enough provenance to attribute a failure causally — upstream context, provider execution, the specialist's own output, the handoff contract, the downstream consumer, or evaluator uncertainty — so a specialist is never blamed for an upstream or provider failure.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schemaVersion", "id", "specialist", "versions", "upstream", "provider",
+    "specialistOutput", "handoff", "downstream", "evaluator"
+  ],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "id": { "type": "string", "minLength": 1 },
+    "specialist": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["role"],
+      "properties": {
+        "role": { "type": "string" },
+        "profileId": { "type": ["string", "null"] },
+        "capabilityClass": { "type": ["string", "null"] }
+      }
+    },
+    "versions": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "taskPacket": { "type": ["string", "null"] },
+        "prompt": { "type": ["string", "null"] },
+        "skill": { "type": ["string", "null"] },
+        "roleFlavor": { "type": ["string", "null"] }
+      }
+    },
+    "upstream": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["evidenceComplete", "inputsPresent"],
+      "properties": {
+        "evidenceComplete": { "type": "boolean" },
+        "inputsPresent": { "type": "boolean" }
+      }
+    },
+    "provider": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["executionError", "degraded"],
+      "properties": {
+        "executionError": { "type": "boolean" },
+        "degraded": { "type": "boolean" }
+      }
+    },
+    "specialistOutput": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["evidenceVerdict"],
+      "properties": {
+        "evidenceVerdict": { "enum": ["pass", "fail", "unverified"] }
+      }
+    },
+    "handoff": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["inputValid", "schemaValid"],
+      "properties": {
+        "inputValid": { "type": "boolean" },
+        "schemaValid": { "type": "boolean" },
+        "output": { "type": ["object", "null"] }
+      }
+    },
+    "downstream": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["consumerError", "outcome"],
+      "properties": {
+        "consumerError": { "type": "boolean" },
+        "outcome": { "enum": ["accepted", "rejected", "unknown"] }
+      }
+    },
+    "evaluator": {
+      "type": "object",
+      "additionalProperties": true,
+      "required": ["abstained"],
+      "properties": {
+        "abstained": { "type": "boolean" },
+        "confidence": { "type": ["number", "null"] }
+      }
+    },
+    "cost": { "type": ["number", "null"] },
+    "latencyMs": { "type": ["number", "null"] },
+    "toolTimeline": { "type": "array", "items": { "type": "object" } },
+    "sourceTraceIds": { "type": "array", "items": { "type": "string" } },
+    "humanCorrection": {
+      "oneOf": [
+        { "type": "null" },
+        {
+          "type": "object",
+          "additionalProperties": true,
+          "required": ["target"],
+          "properties": {
+            "target": { "enum": ["specialist", "upstream", "contract", "downstream", "provider"] }
+          }
+        }
+      ]
+    }
+  }
+}

package/schemas/team.schema.json

@@ -0,0 +1,99 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://geraldmaron.github.io/construct/schemas/team.schema.json",
+  "title": "Construct Team",
+  "description": "A team is an explicitly-defined organizational unit with clear accountability, decision rights, forbidden decisions, escalation paths, and contact info. Teams are the primary organizational structure in the redesigned model.",
+  "type": "object",
+  "required": ["id", "name", "owner", "roles", "charter"],
+  "additionalProperties": false,
+  "properties": {
+    "kind": { "type": "string", "enum": ["group", "squad"] },
+    "groupId": { "type": "string" },
+    "squads": { "type": "array", "items": { "type": "string" } },
+    "collaborators": { "type": "array", "items": { "type": "string" } },
+    "specialists": { "type": "array", "items": { "type": "string" } },
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]{1,40}$",
+      "description": "Unique team identifier (e.g., product-group, platform-group, research-group). Used in policy gates and escalation paths."
+    },
+    "name": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 80,
+      "description": "Human-readable team name (e.g., Product Group, Platform Group, Research Group)."
+    },
+    "owner": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]{1,40}$",
+      "description": "Role id of the team owner/lead (e.g., product-manager, platform-engineer, researcher). This person holds primary accountability for team decisions."
+    },
+    "roles": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 20,
+      "description": "List of role ids that constitute this team.",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9-]{1,40}$"
+      }
+    },
+    "decisionRights": {
+      "type": "array",
+      "description": "Decisions this team is authorized to make. Examples: intake-triage, design-approval, deployment, scope-change, etc.",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9-]{1,40}$"
+      }
+    },
+    "forbiddenDecisions": {
+      "type": "array",
+      "description": "Decisions this team explicitly cannot make. Attempts to make forbidden decisions escalate automatically.",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9-]{1,40}$"
+      }
+    },
+    "escalationPath": {
+      "type": "array",
+      "description": "Chain of escalation for unresolved decisions. First element is the team owner, then subsequent elements for higher-level escalation.",
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z][a-z0-9-]{1,40}$"
+      }
+    },
+    "charter": {
+      "type": "string",
+      "minLength": 20,
+      "maxLength": 800,
+      "description": "One-paragraph mission statement: what this team owns, what it doesn't own, and key constraints. Written in voice of accountability, not aspiration."
+    },
+    "contact": {
+      "type": "object",
+      "description": "How to reach this team.",
+      "additionalProperties": false,
+      "properties": {
+        "slack": {
+          "type": "string",
+          "description": "Slack channel (e.g., #product, #platform)."
+        },
+        "email": {
+          "type": "string",
+          "format": "email",
+          "description": "Team email address (e.g., product@example.com)."
+        },
+        "owner": {
+          "type": "string",
+          "description": "Direct contact for the team owner (name or email)."
+        }
+      }
+    },
+    "evidence": {
+      "type": "array",
+      "description": "Primary sources justifying this team's structure (interviews, job specs, ADRs, organizational research).",
+      "items": {
+        "type": "string"
+      }
+    }
+  }
+}