@geraldmaron/construct 1.4.0 → 1.4.2

package/schemas/platform-capabilities.schema.json

@@ -0,0 +1,83 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://construct.dev/schemas/platform-capabilities.schema.json",
+  "title": "Platform Capability Registry",
+  "description": "Declarative source of truth for what each host platform (Claude Code, Codex, OpenCode, Cursor, VS Code, Copilot) can do. Consumed by the sync and init code so per-host behavior is declared data, not inline branches. See docs/decisions/adr/0033-platform-capability-registry.md.",
+  "type": "object",
+  "required": ["version", "hosts"],
+  "additionalProperties": false,
+  "properties": {
+    "$schema": { "type": "string" },
+    "version": { "type": "integer", "const": 1 },
+    "hosts": {
+      "type": "object",
+      "minProperties": 1,
+      "additionalProperties": { "$ref": "#/definitions/host" }
+    }
+  },
+  "definitions": {
+    "host": {
+      "type": "object",
+      "required": [
+        "displayName",
+        "hasNativeSubagents",
+        "instructionsOnly",
+        "supportsMcp",
+        "configFormat",
+        "localModelProvisioning",
+        "hooks",
+        "globalMcpAllowlist"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "displayName": {
+          "type": "string",
+          "description": "Human-facing host name as reported by host-capabilities detection; also the key in the displayName-to-id lookup."
+        },
+        "hasNativeSubagents": {
+          "type": "boolean",
+          "description": "True when the host routes subagents itself (OpenCode, Cursor, VS Code). When true, the static specialist roster is NOT injected into the system prompt; the host resolves the chain at runtime via orchestration_policy."
+        },
+        "instructionsOnly": {
+          "type": "boolean",
+          "description": "True when the host accepts only instruction text (no agents, no MCP) — Copilot."
+        },
+        "supportsMcp": {
+          "type": "boolean",
+          "description": "True when the host can register MCP servers."
+        },
+        "configFormat": {
+          "type": "string",
+          "enum": ["json", "toml", "markdown"],
+          "description": "Native config serialization for the host."
+        },
+        "localModelProvisioning": {
+          "type": "string",
+          "enum": ["modelfile", "none"],
+          "description": "How the host provisions local-model context windows. 'modelfile' = Ollama Modelfile variants (OpenCode). 'none' = not applicable."
+        },
+        "hooks": {
+          "type": "object",
+          "required": ["supported", "globalAllowlist"],
+          "additionalProperties": false,
+          "properties": {
+            "supported": {
+              "type": "boolean",
+              "description": "True when the host runs lifecycle hooks (Claude Code only today)."
+            },
+            "globalAllowlist": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Hook group ids permitted at user/global scope (safety-only subset). Empty unless hooks.supported is true."
+            }
+          }
+        },
+        "globalMcpAllowlist": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "MCP server ids permitted at user/global scope. Empty unless the host supports MCP at global scope."
+        }
+      }
+    }
+  }
+}

package/schemas/project-config.schema.json

@@ -0,0 +1,227 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://geraldmaron.github.io/construct/schemas/project-config.schema.json",
+  "title": "Construct Project Configuration",
+  "description": "Schema for construct.config.json, the source of truth for project-level Construct settings. Shared and committed to the repo.",
+  "type": "object",
+  "required": ["version"],
+  "additionalProperties": true,
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Reference to the JSON Schema for this file."
+    },
+    "version": {
+      "type": "number",
+      "description": "The configuration schema version.",
+      "default": 1
+    },
+    "alias": {
+      "type": "string",
+      "description": "The display name for this Construct project instance.",
+      "maxLength": 120,
+      "default": "Construct"
+    },
+    "scope": {
+      "type": "string",
+      "description": "The active organizational scope ID. Determines which specialists and capabilities are available.",
+      "enum": ["rnd", "operations", "creative", "research"],
+      "default": "rnd"
+    },
+    "deployment": {
+      "type": "object",
+      "description": "Deployment and infrastructure settings.",
+      "properties": {
+        "mode": {
+          "type": "string",
+          "description": "The operational mode of the Construct instance.",
+          "enum": ["solo", "team", "enterprise"],
+          "default": "solo"
+        },
+        "mcpBroker": {
+          "type": "string",
+          "description": "Controls the engagement of the MCP (Model Context Protocol) broker.",
+          "enum": ["auto", "on", "off"],
+          "default": "auto"
+        },
+        "projectName": {
+          "type": ["string", "null"],
+          "description": "The unique name of the project. Used for multi-project telemetry and storage."
+        },
+        "tenantId": {
+          "type": ["string", "null"],
+          "description": "The tenant ID for enterprise deployments."
+        }
+      }
+    },
+    "orchestration": {
+      "type": "object",
+      "description": "Agent orchestration and workflow strategy.",
+      "properties": {
+        "workerBackend": {
+          "type": "string",
+          "description": "The execution environment for orchestrated workers.",
+          "enum": ["inline", "provider"],
+          "default": "inline"
+        },
+        "store": {
+          "type": "string",
+          "description": "The storage engine for orchestration state and task graphs.",
+          "enum": ["filesystem", "sqlite", "postgres"],
+          "default": "filesystem"
+        },
+        "chainOfThought": {
+          "type": "string",
+          "description": "Disclosure of a provider-executed specialist's reasoning during orchestration. 'hidden': reasoning is not requested or shown. 'surface': reasoning is requested and attached to each task so the CLI, MCP, and dashboard display it. 'telemetry_only': reasoning is requested and written to the run trace but never displayed.",
+          "enum": ["hidden", "surface", "telemetry_only"],
+          "default": "hidden",
+          "examples": ["hidden", "surface", "telemetry_only"]
+        }
+      }
+    },
+    "telemetry": {
+      "type": "object",
+      "description": "Observability and usage tracking settings.",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Whether to record session traces and token usage.",
+          "default": true
+        }
+      }
+    },
+    "ingest": {
+      "type": "object",
+      "description": "Strategy for ingesting and indexing project documents.",
+      "properties": {
+        "strategy": {
+          "type": "string",
+          "description": "The primary mechanism for extracting text from files.",
+          "enum": ["adapter", "provider"],
+          "default": "adapter"
+        },
+        "fallback": {
+          "type": "string",
+          "description": "The secondary mechanism if the primary strategy fails.",
+          "enum": ["none", "provider", "adapter"],
+          "default": "none"
+        },
+        "orchestration": {
+          "type": "string",
+          "description": "Determines if intake processing is a simple prompt or an orchestrated workflow.",
+          "enum": ["prompt-only", "orchestrated"],
+          "default": "prompt-only"
+        }
+      }
+    },
+    "hosts": {
+      "type": "object",
+      "description": "Granular control over editor and platform adapter sets.",
+      "properties": {
+        "claude": { "type": "object", "properties": { "enabled": { "type": "boolean" } } },
+        "opencode": { "type": "object", "properties": { "enabled": { "type": "boolean" } } },
+        "codex": { "type": "object", "properties": { "enabled": { "type": "boolean" } } },
+        "copilot": { "type": "object", "properties": { "enabled": { "type": "boolean" } } },
+        "vscode": { "type": "object", "properties": { "enabled": { "type": "boolean" } } },
+        "cursor": { "type": "object", "properties": { "enabled": { "type": "boolean" } } }
+      }
+    },
+    "providers": {
+      "type": "object",
+      "description": "Provider-specific settings (e.g., Anthropic, OpenAI, GitHub). Values starting with '$' are interpolated from environment variables.",
+      "additionalProperties": true
+    },
+    "sources": {
+      "type": "object",
+      "description": "Typed integration source targets for embed auto-discovery and provider_fetch.",
+      "properties": {
+        "targets": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["id", "provider", "selector"],
+            "properties": {
+              "id": { "type": "string" },
+              "provider": { "type": "string", "enum": ["github", "jira", "linear", "slack"] },
+              "selector": { "type": "object" }
+            }
+          }
+        }
+      }
+    },
+    "intakePolicy": {
+      "type": "object",
+      "description": "Filesystem inbox watcher policy. The canonical drop zone is inbox/ at the project root (always watched, ADR-0045 §C); maxDepth and additionalDirs tune the scan.",
+      "properties": {
+        "maxDepth": { "type": "number", "default": 4, "description": "Subdirectory scan depth per watched directory" },
+        "additionalDirs": { "type": "array", "items": { "type": "string" }, "description": "Extra directories to watch beyond inbox/ (opt-in)" }
+      }
+    },
+    "artifactWorkflow": {
+      "type": "object",
+      "description": "Project overrides for manifest-backed artifact workflows. Per-invocation overrides take precedence over these values, which take precedence over Construct defaults.",
+      "properties": {
+        "defaults": { "type": "object" },
+        "types": { "type": "object", "additionalProperties": { "type": "object" } }
+      }
+    },
+    "models": {
+      "type": "object",
+      "description": "Model catalog visibility and live polling preferences.",
+      "properties": {
+        "visibility": {
+          "type": "object",
+          "properties": {
+            "mode": {
+              "type": "string",
+              "enum": ["all_configured", "tier_defaults", "explicit"],
+              "default": "all_configured"
+            },
+            "include": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Allowlist used when mode is explicit."
+            },
+            "exclude": {
+              "type": "array",
+              "items": { "type": "string" },
+              "description": "Model ids hidden from pickers (active pin still shown with warning)."
+            },
+            "providers": {
+              "type": "object",
+              "description": "Per provider-family toggles; false hides the family from pickers.",
+              "additionalProperties": { "type": "boolean" }
+            }
+          }
+        },
+        "catalog": {
+          "type": "object",
+          "properties": {
+            "liveOpenRouter": {
+              "type": "boolean",
+              "default": true,
+              "description": "Merge cached live OpenRouter free models into the catalog."
+            },
+            "maxLiveFree": {
+              "type": "number",
+              "default": 24,
+              "description": "Maximum live free models merged from cache."
+            }
+          }
+        }
+      }
+    },
+    "resources": {
+      "type": "object",
+      "description": "Storage and runtime resource limits.",
+      "properties": {
+        "disk": {
+          "type": "object",
+          "properties": {
+            "totalCxMaxMb": { "type": "number", "description": "Maximum disk usage for the .cx/ directory (MB).", "default": 2000 }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/project-demo.schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://construct.dev/schemas/project-demo.schema.json",
+  "title": "Construct project demo plug-in manifest",
+  "description": "Schema for .cx/demos/<name>.project.json — a project-defined demo plug-in scaffolded by `construct demo init --from-project`. Declares a project-local demo and the script plus terminal tape it ships with. Project runtime state; gitignored in consuming projects.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema", "name", "title", "project", "script"],
+  "properties": {
+    "$schema": {
+      "type": "string",
+      "description": "Reference to the JSON Schema for this file."
+    },
+    "schema": {
+      "type": "string",
+      "description": "Schema identifier and version for this manifest.",
+      "const": "construct/project-demo/1"
+    },
+    "name": {
+      "type": "string",
+      "description": "Demo id (matches the scaffolded file basename).",
+      "minLength": 1,
+      "pattern": "^[a-z0-9][a-z0-9-]*$"
+    },
+    "title": {
+      "type": "string",
+      "description": "Human-readable demo title.",
+      "minLength": 1
+    },
+    "summary": {
+      "type": "string",
+      "description": "One-line description of what the demo walks through."
+    },
+    "project": {
+      "type": "string",
+      "description": "The host project name this demo belongs to, seeded from real project signals (.cx/context.json, package.json, or directory name).",
+      "minLength": 1
+    },
+    "script": {
+      "type": "string",
+      "description": "Repo-relative path to the demo script under .cx/demos/scripts/.",
+      "pattern": "^\\.cx/demos/scripts/.+\\.json$"
+    },
+    "tape": {
+      "type": "string",
+      "description": "Repo-relative path to the terminal VHS tape stub under .cx/demos/tapes/."
+    },
+    "fallbackSurface": {
+      "type": "string",
+      "description": "Surface to fall back to when the requested demo runner is unavailable.",
+      "enum": ["tape", "playwright"],
+      "default": "tape"
+    },
+    "createdAt": {
+      "type": "string",
+      "description": "ISO-8601 timestamp the scaffold was written.",
+      "format": "date-time"
+    }
+  }
+}

package/schemas/provider-behavior-matrix.schema.json

@@ -0,0 +1,91 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://construct.dev/schemas/provider-behavior-matrix.schema.json",
+  "title": "Construct Provider/Model Behavior Matrix",
+  "description": "Baseline evidence producer for the ExecutionCapabilityProfile (construct-6zga.1.8). Records measured execution behavior keyed by structural capability class — never by vendor name. Each observation carries an evidence provenance so the profile can declare where every field came from.",
+  "type": "object",
+  "required": ["version", "observations"],
+  "additionalProperties": false,
+  "properties": {
+    "version": { "type": "integer", "minimum": 1 },
+    "description": { "type": "string" },
+    "observations": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/observation" }
+    }
+  },
+  "$defs": {
+    "capabilityClass": {
+      "enum": ["hosted-direct", "hosted-routed", "local-constrained", "local-capable", "unknown"]
+    },
+    "transport": {
+      "enum": ["direct", "routed", "local", "unknown"]
+    },
+    "evidenceSource": {
+      "enum": ["hermetic_fixture", "live_probe", "provider_metadata", "operator_override"]
+    },
+    "observation": {
+      "type": "object",
+      "required": ["capabilityClass", "transport", "adapterProtocol", "requestShape", "toolCall", "cancellation", "usage", "contextFailureBehavior", "fallbackClassification", "evidence"],
+      "additionalProperties": false,
+      "properties": {
+        "capabilityClass": { "$ref": "#/$defs/capabilityClass" },
+        "transport": { "$ref": "#/$defs/transport" },
+        "adapterProtocol": { "type": "string", "minLength": 1 },
+        "responseModelId": { "type": ["string", "null"] },
+        "requestShape": {
+          "type": "object",
+          "required": ["system", "toolSchemaCount", "toolSchemaTokenEstimate"],
+          "additionalProperties": false,
+          "properties": {
+            "system": { "enum": ["accepted", "rejected", "ignored", "unknown"] },
+            "toolSchemaCount": { "type": "integer", "minimum": 0 },
+            "toolSchemaTokenEstimate": { "type": "integer", "minimum": 0 }
+          }
+        },
+        "toolCall": {
+          "type": "object",
+          "required": ["supported", "parseShape", "resultShape"],
+          "additionalProperties": false,
+          "properties": {
+            "supported": { "type": "boolean" },
+            "parseShape": { "enum": ["native_tool_use", "openai_function", "none", "unknown"] },
+            "resultShape": { "enum": ["tool_result_block", "message_role_tool", "none", "unknown"] }
+          }
+        },
+        "cancellation": {
+          "type": "object",
+          "required": ["supported", "mechanism"],
+          "additionalProperties": false,
+          "properties": {
+            "supported": { "type": "boolean" },
+            "mechanism": { "enum": ["abort_signal", "none", "unknown"] }
+          }
+        },
+        "usage": {
+          "type": "object",
+          "required": ["fields", "cost"],
+          "additionalProperties": false,
+          "properties": {
+            "fields": { "type": "array", "items": { "type": "string" } },
+            "cost": { "type": "boolean" }
+          }
+        },
+        "contextFailureBehavior": { "enum": ["error", "truncate", "silent_drop", "unknown"] },
+        "fallbackClassification": { "enum": ["retryable", "fatal", "rate_limited", "model_unavailable", "unknown"] },
+        "evidence": {
+          "type": "object",
+          "required": ["source", "redacted", "runs"],
+          "additionalProperties": false,
+          "properties": {
+            "source": { "$ref": "#/$defs/evidenceSource" },
+            "capturedAt": { "type": ["string", "null"] },
+            "redacted": { "type": "boolean" },
+            "runs": { "type": "integer", "minimum": 1 },
+            "distribution": { "type": ["object", "null"] }
+          }
+        }
+      }
+    }
+  }
+}

package/schemas/scope.schema.json

@@ -0,0 +1,197 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://geraldmaron.github.io/construct/schemas/scope.schema.json",
+  "title": "Construct work scope",
+  "description": "A curated or user-defined work scope. Drives intake taxonomy, doc templates, hooks, and default skills. Teams and roles load from specialists/org at runtime — do not author them here.",
+  "type": "object",
+  "required": ["id", "displayName", "intake"],
+  "additionalProperties": false,
+  "properties": {
+    "id": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9-]{1,30}$",
+      "description": "Lowercase id used in config and CLI flags."
+    },
+    "displayName": { "type": "string", "minLength": 1, "maxLength": 60 },
+    "tagline": { "type": "string", "maxLength": 120 },
+    "extends": { "type": ["string", "null"] },
+    "custom": { "type": "boolean", "default": false },
+    "experimental": {
+      "type": "boolean",
+      "description": "Scope borrows the shared org; excluded from certification until dedicated workflow agents exist."
+    },
+    "roles": {
+      "type": "array",
+      "maxItems": 80,
+      "description": "Custom profiles only. Curated scopes derive roles from specialists/org.",
+      "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,40}$" }
+    },
+    "teams": {
+      "type": "array",
+      "maxItems": 12,
+      "description": "Custom profiles only. Curated scopes derive teams from specialists/org.",
+      "items": {
+        "type": "object",
+        "required": ["id", "name", "owner", "roles", "charter"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,40}$" },
+          "name": { "type": "string", "minLength": 1, "maxLength": 80 },
+          "owner": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,40}$", "description": "Primary owner/lead role for this team." },
+          "roles": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 20,
+            "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,40}$" }
+          },
+          "decisionRights": {
+            "type": "array",
+            "description": "Decisions this team is authorized to make.",
+            "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,40}$" }
+          },
+          "forbiddenDecisions": {
+            "type": "array",
+            "description": "Decisions this team explicitly cannot make.",
+            "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,40}$" }
+          },
+          "escalationPath": {
+            "type": "array",
+            "description": "Escalation chain for unresolved decisions.",
+            "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,40}$" }
+          },
+          "charter": { "type": "string", "minLength": 20, "maxLength": 800, "description": "Mission statement: what this team owns, what it doesn't, and key constraints." },
+          "contact": {
+            "type": "object",
+            "additionalProperties": false,
+            "properties": {
+              "slack": { "type": "string" },
+              "email": { "type": "string", "format": "email" },
+              "owner": { "type": "string" }
+            }
+          },
+          "evidence": {
+            "type": "array",
+            "description": "Primary sources justifying this team's structure.",
+            "items": { "type": "string" }
+          }
+        }
+      }
+    },
+    "departments": {
+      "type": "array",
+      "maxItems": 12,
+      "description": "Deprecated. Synthesized at runtime from teams when absent. Do not author in curated profiles.",
+      "items": {
+        "type": "object",
+        "required": ["id", "displayName", "charter", "roles"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,40}$" },
+          "displayName": { "type": "string", "minLength": 1, "maxLength": 60 },
+          "charter": { "type": "string", "minLength": 20, "maxLength": 600, "description": "One-paragraph mission statement: what this department owns, what it does not own, who it hands off to." },
+          "roles": {
+            "type": "array",
+            "minItems": 1,
+            "maxItems": 20,
+            "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,40}$" }
+          },
+          "evidence": {
+            "type": "array",
+            "description": "Primary sources used to justify this department exists (interview transcripts, public job specs, ADRs). Required when promoting from draft.",
+            "items": { "type": "string" }
+          }
+        }
+      }
+    },
+    "intake": {
+      "type": "object",
+      "required": ["types", "stages"],
+      "additionalProperties": false,
+      "properties": {
+        "types": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 24,
+          "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,30}$" }
+        },
+        "stages": {
+          "type": "array",
+          "minItems": 1,
+          "maxItems": 12,
+          "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,30}$" }
+        },
+        "classificationTable": {
+          "type": ["string", "null"],
+          "description": "Module path resolved relative to repo root. Optional. B2 ships per-profile tables for the curated set."
+        }
+      }
+    },
+    "docTemplates": {
+      "type": "array",
+      "maxItems": 30,
+      "items": { "type": "string", "pattern": "^[a-z][a-z0-9-]{1,40}$" }
+    },
+    "hooks": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "sessionReflect": { "type": "string", "enum": ["on", "off"] },
+        "sessionOptimize": { "type": "string", "enum": ["on", "off"] }
+      }
+    },
+    "defaultSkills": {
+      "type": "array",
+      "maxItems": 30,
+      "items": { "type": "string" }
+    },
+    "toneDefaults": {
+      "type": "object",
+      "description": "Maps doc type id to tone profile id from specialists/tone-profiles.json",
+      "additionalProperties": { "type": "string" }
+    },
+    "researchProfiles": {
+      "type": "object",
+      "description": "Maps intake type id to research profile: external, user, codebase, market, compliance",
+      "additionalProperties": {
+        "type": "string",
+        "enum": ["external", "user", "codebase", "market", "compliance"]
+      }
+    },
+    "rebrand": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "intakeQueueLabel": { "type": "string", "maxLength": 60 },
+        "signalNoun": { "type": "string", "maxLength": 30 }
+      }
+    },
+    "capabilities": {
+      "type": "object",
+      "additionalProperties": false,
+      "description": "Optional capability flags. Each one toggles a generic Construct subsystem on for the profile. Adding a capability never changes the role set; it changes which scaffolding init applies and which runtime helpers are exposed.",
+      "properties": {
+        "intake": {
+          "type": "object",
+          "additionalProperties": false,
+          "description": "The project ingests raw files into structured artifacts. Init scaffolds inbox/, the dedup manifest, and stamps attribution metadata when this is on.",
+          "properties": {
+            "inbox": {
+              "type": "boolean",
+              "description": "Scaffold inbox/ at the project root with a permissive .gitignore (everything except the .gitignore itself) so raw drops never end up in source."
+            },
+            "dedup": {
+              "type": "string",
+              "enum": ["sha256", "none"],
+              "default": "sha256",
+              "description": "Content-hash dedup for processed files. sha256 is the default; none disables the manifest."
+            },
+            "attribution": {
+              "type": "boolean",
+              "description": "Stamp createdBy / createdByAgent / createdAt on every intake-produced artifact."
+            }
+          }
+        }
+      }
+    }
+  }
+}