@geraldmaron/construct 1.4.1 → 1.4.2

package/schemas/unified-registry.schema.json

@@ -0,0 +1,548 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://geraldmaron.github.io/construct/schemas/unified-registry.schema.json",
+  "title": "Construct Unified Registry",
+  "description": "Single source of truth for teams, specialists, roles, contracts, and policies. Consolidates what was previously split across five separate files: teams.json, teams-registry.json, registry.json, contracts.json, and role-manifests.json.",
+  "type": "object",
+  "required": ["version", "teams", "specialists", "contracts", "policies"],
+  "additionalProperties": false,
+  "properties": {
+    "version": {
+      "enum": [2, 3],
+      "description": "Schema version. Version 3 is the modular org assembly."
+    },
+    "teams": {
+      "type": "object",
+      "description": "Map of team id -> team definition. Teams are the primary organizational unit with explicit decision rights, escalation paths, and charter.",
+      "additionalProperties": {
+        "$ref": "#/$defs/team"
+      },
+      "minProperties": 1
+    },
+    "specialists": {
+      "type": "object",
+      "description": "Map of specialist id (e.g., cx-engineer) -> specialist definition. Every specialist declares exactly one team.",
+      "additionalProperties": {
+        "$ref": "#/$defs/specialist"
+      },
+      "minProperties": 1
+    },
+    "contracts": {
+      "type": "object",
+      "description": "Map of contract id -> contract definition. Contracts are producer→consumer handoffs with preconditions, postconditions, and schemas.",
+      "additionalProperties": {
+        "$ref": "#/$defs/contract"
+      }
+    },
+    "policies": {
+      "type": "object",
+      "description": "Map of policy id -> policy definition. Policies enforce team decision rights, approval requirements, and governance gates.",
+      "additionalProperties": {
+        "$ref": "#/$defs/policy"
+      }
+    }
+  },
+  "$defs": {
+    "team": {
+      "type": "object",
+      "description": "Organizational team with explicit owner, decision rights, forbidden decisions, escalation path, and charter.",
+      "required": ["id", "name", "owner", "roles", "charter"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]{1,40}$",
+          "description": "Unique team identifier (e.g., product-group, engineering-group, quality-group)."
+        },
+        "name": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 80,
+          "description": "Human-readable team name."
+        },
+        "owner": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]{1,40}$",
+          "description": "Role id of the team owner/lead. Must be a role that has at least one specialist assigned."
+        },
+        "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 (e.g., intake-triage, design-approval, deployment, scope-change).",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z][a-z0-9-]{1,40}$"
+          }
+        },
+        "forbiddenDecisions": {
+          "type": "array",
+          "description": "Decisions this team explicitly cannot make. Attempts 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 role, then higher-level escalations.",
+          "minItems": 1,
+          "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."
+        },
+        "contact": {
+          "type": "object",
+          "description": "How to reach this team.",
+          "additionalProperties": false,
+          "properties": {
+            "slack": {
+              "type": "string",
+              "description": "Slack channel (e.g., #product, #engineering)."
+            },
+            "email": {
+              "type": "string",
+              "format": "email",
+              "description": "Team email address."
+            },
+            "owner": {
+              "type": "string",
+              "description": "Direct contact for the team owner."
+            }
+          }
+        },
+        "evidence": {
+          "type": "array",
+          "description": "Primary sources justifying this team's structure (interviews, job specs, ADRs, organizational research).",
+          "items": {
+            "type": "string"
+          }
+        },
+        "sources": {
+          "type": "array",
+          "description": "Integration resources this team binds (GitHub repos, Jira/Linear projects, Slack channels) with typed selectors and optional filters. Resolved by resolveTeamSources() and threaded into embed/provider_fetch.",
+          "items": { "$ref": "#/$defs/sourceTarget" }
+        }
+      }
+    },
+    "sourceTarget": {
+      "type": "object",
+      "description": "A typed integration binding. Deep-validated at runtime by lib/config/source-targets.mjs validateSourceTarget.",
+      "required": ["id", "provider", "selector"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[A-Za-z0-9_-]{1,64}$",
+          "description": "Stable id for this binding (unique within the team's sources)."
+        },
+        "provider": {
+          "type": "string",
+          "enum": ["github", "jira", "linear", "slack"],
+          "description": "Integration provider."
+        },
+        "selector": {
+          "type": "object",
+          "description": "Provider-specific selector (github: {repo}, jira: {project}, linear: {team}, slack: {channel, intent?}).",
+          "minProperties": 1
+        },
+        "filters": {
+          "type": "object",
+          "description": "Optional per-target filters threaded into fetch (e.g., jira {jql}, github {refs, limit}, slack {oldest})."
+        }
+      }
+    },
+    "specialist": {
+      "type": "object",
+      "description": "An AI specialist (cx-* agent) with skills, fence, model tier, and event watchers.",
+      "required": ["name", "team"],
+      "additionalProperties": false,
+      "properties": {
+        "name": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]{1,40}$",
+          "description": "Specialist id without cx- prefix (e.g., engineer, qa, architect). Combined with prefix to create cx-engineer, cx-qa, etc."
+        },
+        "displayName": {
+          "type": "string",
+          "description": "Human-readable specialist name (e.g., Engineer, Quality Assurance, Architect)."
+        },
+        "description": {
+          "type": "string",
+          "description": "Short description of what this specialist does."
+        },
+        "team": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]{1,40}$",
+          "description": "Team id this specialist belongs to. Every specialist declares exactly one team."
+        },
+        "role": {
+          "type": "string",
+          "enum": ["owner", "member", "temporary"],
+          "description": "Role within the team: owner (team lead), member (regular), or temporary."
+        },
+        "modelTier": {
+          "type": "string",
+          "enum": ["standard", "reasoning"],
+          "description": "Which model tier to use for this specialist: standard or reasoning."
+        },
+        "reasoningEffort": {
+          "type": "string",
+          "enum": ["low", "medium", "high"],
+          "description": "Effort level for extended thinking (if using reasoning model)."
+        },
+        "skills": {
+          "type": "array",
+          "description": "List of skill paths this specialist has (e.g., docs/prd-workflow, architecture/api-design).",
+          "items": {
+            "type": "string"
+          }
+        },
+        "events": {
+          "type": "array",
+          "description": "Trigger events that activate this specialist (e.g., test.fail, handoff.received, pr.opened).",
+          "items": {
+            "type": "string"
+          }
+        },
+        "fence": {
+          "type": "object",
+          "description": "Access control fence for this specialist.",
+          "additionalProperties": false,
+          "properties": {
+            "allowedPaths": {
+              "type": "array",
+              "description": "Paths/glob patterns this specialist can read/write.",
+              "items": {
+                "type": "string"
+              }
+            },
+            "allowedCommands": {
+              "type": "array",
+              "description": "Commands this specialist can execute (bash, bd, git, etc.).",
+              "items": {
+                "type": "string"
+              }
+            },
+            "allowedBdLabels": {
+              "type": "array",
+              "description": "Beads labels this specialist can use when creating/updating issues.",
+              "items": {
+                "type": "string"
+              }
+            },
+            "approvalRequired": {
+              "type": "array",
+              "description": "Actions requiring approval before execution (e.g., commit, push, edit:lib/**).",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "docArtifacts": {
+          "type": "array",
+          "description": "Doc artifact types this specialist can author (e.g., prd, adr, memo, incident-report).",
+          "items": {
+            "type": "string"
+          }
+        },
+        "watchConditions": {
+          "type": "array",
+          "description": "Conditions that should trigger proactive engagement (e.g., high-ambiguity-deep-work, flaky-tests, stale-alignment-census).",
+          "items": {
+            "type": "string"
+          }
+        },
+        "prompt": {
+          "type": "object",
+          "description": "Optional prompt configuration overrides for this specialist.",
+          "additionalProperties": false,
+          "properties": {
+            "file": {
+              "type": "string",
+              "description": "Path to specialist prompt file."
+            },
+            "customInstructions": {
+              "type": "string",
+              "description": "Custom instructions appended to the base prompt."
+            }
+          }
+        },
+        "permissions": {
+          "type": "object",
+          "description": "Fine-grained permissions (edit, bash, webfetch, etc.).",
+          "additionalProperties": {
+            "type": "string",
+            "enum": ["allow", "deny"]
+          }
+        }
+      }
+    },
+    "contract": {
+      "type": "object",
+      "description": "Service contract between producer and consumer specialists. Defines inputs, outputs, preconditions, postconditions, and team boundaries.",
+      "required": ["id", "producer", "consumer"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]{1,50}$",
+          "description": "Unique contract identifier (e.g., construct-to-orchestrator, researcher-to-architect)."
+        },
+        "producer": {
+          "type": "string",
+          "description": "Specialist id or role that produces the output (e.g., cx-researcher, user, construct)."
+        },
+        "consumer": {
+          "type": "string",
+          "description": "Specialist id or role that consumes the output (e.g., cx-architect, cx-product-manager, construct)."
+        },
+        "trigger": {
+          "type": "object",
+          "description": "Conditions that trigger this contract.",
+          "additionalProperties": true
+        },
+        "input": {
+          "type": "object",
+          "description": "Input shape and requirements.",
+          "additionalProperties": true,
+          "properties": {
+            "shape": {
+              "type": "string",
+              "description": "Named shape (e.g., task-packet, research-brief, evidence-brief)."
+            },
+            "mustContain": {
+              "type": "array",
+              "description": "Fields that must be present in the input.",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "output": {
+          "type": "object",
+          "description": "Output shape and requirements.",
+          "additionalProperties": true,
+          "properties": {
+            "shape": {
+              "type": "string",
+              "description": "Named shape (e.g., routed-plan, decision, prd-handoff)."
+            },
+            "mustContain": {
+              "type": "array",
+              "description": "Fields that must be present in the output.",
+              "items": {
+                "type": "string"
+              }
+            },
+            "schema": {
+              "type": "string",
+              "description": "Path to JSON Schema for the output."
+            }
+          }
+        },
+        "preconditions": {
+          "type": "array",
+          "description": "Conditions that must be true before this contract executes.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "postconditions": {
+          "type": "array",
+          "description": "Conditions that must be true after this contract completes.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "teamBoundary": {
+          "type": "object",
+          "description": "Whether this handoff crosses a team boundary and what approval is needed.",
+          "additionalProperties": false,
+          "properties": {
+            "crosses": {
+              "type": "boolean",
+              "description": "Whether this contract crosses a team boundary."
+            },
+            "producerTeam": {
+              "type": "string",
+              "description": "Team id of the producer."
+            },
+            "consumerTeam": {
+              "type": "string",
+              "description": "Team id of the consumer."
+            },
+            "requiresApprovalFrom": {
+              "type": "array",
+              "description": "Team ids that must approve this cross-team handoff.",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "description": {
+          "type": "string",
+          "description": "Human-readable description of this contract."
+        },
+        "skillHints": {
+          "type": "array",
+          "description": "Optional routing hints — skill ids that inform dispatch context. Producer/consumer ids remain authoritative.",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          },
+          "maxItems": 12
+        }
+      }
+    },
+    "policy": {
+      "type": "object",
+      "description": "Governance policy enforcing team decision rights, approval requirements, and gates.",
+      "required": ["id", "owner"],
+      "additionalProperties": false,
+      "properties": {
+        "id": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]{1,50}$",
+          "description": "Unique policy identifier (e.g., release-gates, security-approval, design-approval)."
+        },
+        "owner": {
+          "type": "string",
+          "pattern": "^[a-z][a-z0-9-]{1,40}$",
+          "description": "Team id that owns and enforces this policy."
+        },
+        "description": {
+          "type": "string",
+          "description": "Human-readable description of what this policy enforces."
+        },
+        "enforcement": {
+          "type": "string",
+          "enum": ["hard", "soft"],
+          "description": "hard = blocks execution, soft = warns but allows."
+        },
+        "mode": {
+          "type": "string",
+          "enum": ["approval", "veto", "audit", "escalation"],
+          "description": "How this policy is enforced: approval (must approve), veto (can block), audit (log only), escalation (route upward)."
+        },
+        "requiresApprovalFrom": {
+          "type": "array",
+          "description": "Team ids that must approve before execution.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "mayVetoFrom": {
+          "type": "array",
+          "description": "Team ids that can veto this decision.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "escalatesTo": {
+          "type": "array",
+          "description": "Team ids to escalate to if blocked or disputed.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "decisionRights": {
+          "type": "array",
+          "description": "Decisions this policy governs (e.g., deployment, scope-change, security-approval).",
+          "items": {
+            "type": "string"
+          }
+        },
+        "conditions": {
+          "type": "array",
+          "description": "Conditions under which this policy applies.",
+          "items": {
+            "type": "string"
+          }
+        },
+        "evidence": {
+          "type": "array",
+          "description": "References to source documents or decisions justifying this policy.",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  },
+  "allOf": [
+    {
+      "description": "Validate that every specialist declares exactly one team, and that team exists.",
+      "not": {
+        "required": ["_validateSpecialistTeams"],
+        "properties": {
+          "_validateSpecialistTeams": {
+            "const": false
+          }
+        }
+      }
+    },
+    {
+      "description": "Validate that every team has at least one specialist assigned to it.",
+      "not": {
+        "required": ["_validateTeamAssignment"],
+        "properties": {
+          "_validateTeamAssignment": {
+            "const": false
+          }
+        }
+      }
+    },
+    {
+      "description": "Validate that every team owner is a role, and that role has at least one specialist.",
+      "not": {
+        "required": ["_validateTeamOwner"],
+        "properties": {
+          "_validateTeamOwner": {
+            "const": false
+          }
+        }
+      }
+    },
+    {
+      "description": "Validate that every contract producer and consumer exist in the specialists map.",
+      "not": {
+        "required": ["_validateContractSpecialists"],
+        "properties": {
+          "_validateContractSpecialists": {
+            "const": false
+          }
+        }
+      }
+    },
+    {
+      "description": "Validate that no specialist names collide across teams.",
+      "not": {
+        "required": ["_validateSpecialistNames"],
+        "properties": {
+          "_validateSpecialistNames": {
+            "const": false
+          }
+        }
+      }
+    }
+  ]
+}

package/scripts/sync-specialists.mjs

@@ -117,7 +117,6 @@ function unifiedToLegacyRegistry(unified) {
   };
 }
 
-clearCache();
 clearCache();
 const unified = loadRegistry({ rootDir: root });
 const registry = unifiedToLegacyRegistry(unified);
@@ -773,7 +772,7 @@ function orchestrationMicroPrompt(platform) {
     `Example — the user says "add rate limiting to the API". Your first action is a tool call, not prose:\n` +
     `  call ${policyTool} { "request": "add rate limiting to the API" }\n` +
     `If the route is focused/orchestrated specialist work, call \`${runTool}\` with the same request. If the route suggests a workflow such as \`research-synthesis\`, pass it as \`workflow_type\`. Do not narrate completed research unless \`${runTool}\` or evidence tools actually ran.\n\n` +
-    `If a request needs a capability you lack — live web/network access, external data, code execution — do not refuse or tell the user to run it themselves. Route it via \`${runTool}\` to the specialist that holds the capability (web access lives with the researcher), or ask one clarifying question when the target is ambiguous.`
+    `If a request needs a capability you lack — live web/network access, external data, code execution — route it via \`${runTool}\` to the specialist that holds it (the researcher performs live web retrieval when a web path is available). Do not tell the user to run it themselves. But if \`${runTool}\` reports the capability was unavailable (degraded with \`capability-unavailable\`, or a prepare-only result), say plainly it could not be reached and return an insufficient-evidence result — never fabricate URLs, dates, quotes, or citations. Ask one clarifying question when the target is ambiguous.`
   );
 }
 
@@ -1368,15 +1367,14 @@ When using this prompt, stay within the role above and adapt to the current repo
 // recognized here, so the orchestrator needs its own VS Code agent or it lists
 // in the picker with no usable tools.
 
-const COPILOT_AGENT_TOOLS = [
-  "construct-mcp/*",
-  "web/fetch",
-  "web/githubRepo",
+export const COPILOT_AGENT_TOOLS = [
+  "construct-mcp/orchestration_policy",
+  "construct-mcp/orchestration_run",
+  "construct-mcp/orchestration_readiness",
   "search/codebase",
   "search/usages",
   "search/fileSearch",
   "read/problems",
-  "edit/editFiles",
 ];
 
 function copilotAgentFile(entry, allEntries) {
@@ -1495,32 +1493,61 @@ function getVSCodeUserMcpPaths() {
 
 export function mcpEntryPointsOutsideToolkit(entry, root) {
   const args = Array.isArray(entry?.args) ? entry.args : [];
-  return args.some(
-    (arg) => typeof arg === "string"
-      && /\/lib\/mcp\/[a-z0-9-]+\.mjs$/.test(arg)
-      && !arg.startsWith(`${root}/`),
-  );
+  return args.some((arg) => {
+    if (typeof arg !== "string") return false;
+    const normalArg = arg.replace(/\\/g, "/");
+    const normalRoot = root.replace(/\\/g, "/");
+    return /\/lib\/mcp\/[a-z0-9-]+\.mjs$/i.test(normalArg)
+      && !normalArg.startsWith(`${normalRoot}/`);
+  });
 }
 
-// VS Code scans both `.github/agents` and `.claude/agents`, so the orchestrator
-// would list twice — once with VS Code tools (.github/agents) and once with
-// Claude tool names VS Code ignores (.claude/agents). `chat.agentFilesLocations`
-// is the documented lever to pin the scan; its power over the built-in
-// `.claude/agents` compatibility scan is version-dependent, so this is a
-// best-effort hint, not a guarantee. Merge only into a strictly-parseable file
-// and never overwrite an existing choice, so a commented (JSONC) or
-// user-customized settings.json is left untouched.
+// Workspace defaults Construct manages for VS Code chat. `chat.agentFilesLocations`
+// pins the agent scan to `.github/agents` so the orchestrator does not list twice
+// (VS Code also scans `.claude/agents`, whose Claude tool names it ignores); its
+// power over that built-in compatibility scan is version-dependent, so it is a
+// best-effort hint. `chat.mcp.autostart` (VS Code ≥1.105, string enum) set to
+// `always` eager-starts MCP servers so `construct-mcp` is live without a manual
+// Start each session — the orchestrator's first move is an MCP call, so a dormant
+// server otherwise reads as "enable the MCP server". Neither removes the one-time
+// per-developer MCP trust grant, which VS Code stores locally, not in committed
+// config. Each key is applied only when unset, and a settings.json that is not
+// strict JSON (commented/JSONC or user-customized) is left untouched.
+
+const VSCODE_MANAGED_SETTINGS = {
+  "chat.agentFilesLocations": { ".github/agents": true, ".claude/agents": false },
+  "chat.mcp.autoStart": "always",
+};
+
+// Strip full-line JSONC comments (`// …`) and trailing commas before JSON.parse.
+// Handles the common VS Code settings.json patterns (line comments, trailing commas);
+// does not attempt to handle inline comments after values.
+
+function parseJsoncContent(text) {
+  const stripped = text
+    .split('\n')
+    .map((line) => {
+      const t = line.trimStart();
+      return t.startsWith('//') ? '' : line;
+    })
+    .join('\n')
+    .replace(/,(\s*[}\]])/g, '$1');
+  return JSON.parse(stripped);
+}
 
-export function pinVscodeAgentLocations(targetDir) {
+export function pinVscodeChatSettings(targetDir) {
   if (DRY_RUN) return;
   const settingsPath = path.join(targetDir, ".vscode", "settings.json");
   let settings = {};
   if (fs.existsSync(settingsPath)) {
-    try { settings = JSON.parse(fs.readFileSync(settingsPath, "utf8")) || {}; }
+    try { settings = parseJsoncContent(fs.readFileSync(settingsPath, "utf8")) || {}; }
     catch { return; }
   }
-  if (settings["chat.agentFilesLocations"]) return;
-  settings["chat.agentFilesLocations"] = { ".github/agents": true, ".claude/agents": false };
+  let changed = false;
+  for (const [key, value] of Object.entries(VSCODE_MANAGED_SETTINGS)) {
+    if (settings[key] === undefined) { settings[key] = value; changed = true; }
+  }
+  if (!changed) return;
   mkdirp(path.dirname(settingsPath));
   fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
 }
@@ -1581,7 +1608,7 @@ function syncVSCode(targetDir = null, wants = true) {
       mkdirp(path.dirname(mcpPath));
       fs.writeFileSync(mcpPath, JSON.stringify(config, null, 2) + "\n");
     }
-    pinVscodeAgentLocations(targetDir);
+    pinVscodeChatSettings(targetDir);
     return true;
   }