@geraldmaron/construct 1.0.7 → 1.0.9

package/lib/cli-commands.mjs

@@ -199,14 +199,6 @@ export const CLI_COMMANDS = [
       { name: 'update', desc: 'Regenerate AUTO-managed regions' },
     ],
   },
-  {
-    name: 'models',
-    emoji: '🧠',
-    category: 'Core',
-    core: true,
-    description: 'Manage AI model assignments',
-    usage: 'construct models [--apply|--poll]',
-  },
   {
     name: 'doctor',
     emoji: '🩺',
@@ -273,145 +265,251 @@ export const CLI_COMMANDS = [
     description: 'Task graph management',
     usage: 'construct graph list|show|from-intake',
   },
+
+  // ── Models & Integrations ─────────────────────────────────────────────
   {
-    name: 'memory',
-    emoji: '💡',
-    category: 'Work',
-    core: false,
-    description: 'Inspect memory layer',
-    usage: 'construct memory stats|consolidate',
-  },
-  {
-    name: 'reflect',
-    emoji: '🪞',
-    category: 'Work',
-    core: false,
-    description: 'Capture improvement feedback',
-    usage: 'construct reflect [--summary=<text>]',
-  },
-  {
-    name: 'drop',
-    emoji: '📥',
-    category: 'Work',
-    core: false,
-    description: 'Ingest file from Downloads/Desktop',
-    usage: 'construct drop [--list]',
-  },
-  {
-    name: 'wireframe',
-    emoji: '✏️',
-    category: 'Work',
-    core: false,
-    description: 'Generate wireframes from description',
-    usage: 'construct wireframe "<description>"',
-  },
-  {
-    name: 'bootstrap',
-    emoji: '🌱',
-    category: 'Work',
-    core: false,
-    description: 'Import seed observations',
-    usage: 'construct bootstrap',
-  },
-  {
-    name: 'team',
-    emoji: '👥',
-    category: 'Work',
-    core: false,
-    description: 'Team review and templates',
-    usage: 'construct team review|templates',
+    name: 'models',
+    emoji: '🧠',
+    category: 'Models & Integrations',
+    description: 'Show or update model tier assignments',
+    usage: 'construct models [--poll|--apply|--reset|--tier=TIER|--set=MODEL|--prefer-free|--prefer-free-same-family]',
+    options: [
+      { flag: '--poll',        desc: 'Query OpenRouter for currently free models' },
+      { flag: '--apply',       desc: 'Auto-apply best free models and sync' },
+      { flag: '--reset',       desc: 'Remove model overrides, restore defaults' },
+      { flag: '--tier=TIER',   desc: 'Target tier: reasoning | standard | fast' },
+      { flag: '--set=MODEL_ID',desc: 'Set specific model for the tier' },
+      { flag: '--prefer-free', desc: 'When inferring sibling tiers, prefer free models where possible' },
+      { flag: '--prefer-free-same-family', desc: 'Prefer free siblings only when they stay in the same provider family' },
+    ],
   },
-  
-  // ── Integrations ──────────────────────────────────────────────────────
   {
     name: 'mcp',
     emoji: '🔌',
-    category: 'Integrations',
-    core: false,
+    category: 'Models & Integrations',
     description: 'Manage MCP integrations',
-    usage: 'construct mcp list|add|remove',
-  },
-  {
-    name: 'ollama',
-    emoji: '🦙',
-    category: 'Integrations',
-    core: false,
-    description: 'Manage local Ollama models',
-    usage: 'construct ollama status|pull|test',
+    usage: 'construct mcp <list|add|remove|info> [name]',
+    subcommands: [
+      { name: 'list',   desc: 'Show all MCP integrations and status' },
+      { name: 'add',    desc: 'Add an MCP integration interactively' },
+      { name: 'remove', desc: 'Remove an MCP integration' },
+      { name: 'info',   desc: 'Show setup details for an integration' },
+    ],
   },
   {
     name: 'plugin',
     emoji: '🧩',
-    category: 'Integrations',
-    core: false,
-    description: 'Manage plugin manifests',
-    usage: 'construct plugin list|validate',
+    category: 'Models & Integrations',
+    description: 'Manage external Construct plugin manifests',
+    usage: 'construct plugin <list|info|validate|init> [name]',
+    subcommands: [
+      { name: 'list', desc: 'Show loaded plugins and manifest sources' },
+      { name: 'info', desc: 'Show details for a plugin' },
+      { name: 'validate', desc: 'Validate all discovered plugin manifests' },
+      { name: 'init', desc: 'Create a starter plugin manifest in .cx/plugins/' },
+    ],
   },
   {
     name: 'hosts',
     emoji: '🖥️',
-    category: 'Integrations',
-    core: false,
-    description: 'Check host capabilities',
+    category: 'Models & Integrations',
+    description: 'Show host support for Construct orchestration',
     usage: 'construct hosts',
   },
   {
     name: 'claude:allow',
     emoji: '🔓',
-    category: 'Integrations',
-    core: false,
-    description: 'Manage Claude Code permissions',
-    usage: 'construct claude:allow list|add|check',
+    category: 'Models & Integrations',
+    description: 'Manage Claude Code `permissions.allow` from the outside (auto-classifier blocks the agent from editing it)',
+    usage: 'construct claude:allow <list|add|remove|check> [pattern...] [--apply]',
+    subcommands: [
+      { name: 'list',   desc: 'Print every allowlist entry' },
+      { name: 'add',    desc: 'Add one or more patterns (idempotent)' },
+      { name: 'remove', desc: 'Remove patterns' },
+      { name: 'check',  desc: 'Detect branch-prefix gaps; `--apply` writes the suggestions' },
+    ],
   },
-  
+
   // ── Observability ─────────────────────────────────────────────────────
   {
-    name: 'cost',
-    emoji: '💰',
+    name: 'review',
+    emoji: '📈',
     category: 'Observability',
-    core: false,
-    description: 'Token usage and cost breakdown',
-    usage: 'construct cost [--days=N]',
+    description: 'Generate agent performance review from Langfuse trace backend',
+    usage: 'construct review [--days=N] [--agent=NAME] [--schedule]',
+    options: [
+      { flag: '--days=N',      desc: 'Review window in days (default: 30)' },
+      { flag: '--agent=NAME',  desc: 'Filter to a specific agent' },
+      { flag: '--out=PATH',    desc: 'Output directory' },
+      { flag: '--json-only',   desc: 'Write raw JSON only, skip markdown report' },
+      { flag: '--schedule',    desc: 'Schedule automatic weekly reviews' },
+      { flag: '--cadence=CRON',desc: 'Cron expression for --schedule (default: Monday 9am)' },
+    ],
   },
   {
-    name: 'efficiency',
-    emoji: '🧮',
+    name: 'optimize',
+    emoji: '⚙️',
     category: 'Observability',
-    core: false,
-    description: 'Read efficiency metrics',
-    usage: 'construct efficiency',
+    description: 'Prompt optimization using Langfuse trace quality scores',
+    usage: 'construct optimize <agent> [--dry-run] [--list]',
+    options: [
+      { flag: '--dry-run',       desc: 'Preview changes without applying' },
+      { flag: '--list',          desc: 'Show all agents with quality scores' },
+      { flag: '--threshold=N',   desc: 'Quality threshold to trigger optimization (default: 0.7)' },
+      { flag: '--days=N',        desc: 'Trace window in days (default: 7)' },
+      { flag: '--min-traces=N',  desc: 'Minimum traces required (default: 20)' },
+    ],
   },
   {
-    name: 'review',
-    emoji: '📈',
+    name: 'telemetry-backfill',
+    emoji: '🩹',
     category: 'Observability',
-    core: false,
-    description: 'Agent performance review',
-    usage: 'construct review [--days=N]',
+    description: 'Backfill sparse traces with observations (trace backend)',
+    usage: 'construct telemetry-backfill [--limit=N]',
+    options: [
+      { flag: '--limit=N', desc: 'Maximum sparse traces to backfill (default: 10)' },
+      { flag: '--best-effort', desc: 'Skip failures instead of exiting non-zero' },
+    ],
   },
   {
-    name: 'optimize',
-    emoji: '⚙️',
+    name: 'eval-datasets',
+    emoji: '📊',
     category: 'Observability',
-    core: false,
-    description: 'Prompt optimization',
-    usage: 'construct optimize <agent>',
+    description: 'Sync scored Langfuse traces into eval datasets for prompt regression testing',
+    usage: 'construct eval-datasets [--limit=N]',
+    options: [
+      { flag: '--limit=N', desc: 'Maximum scored traces to sync (default: 100)' },
+    ],
+  },
+  {
+    name: 'llm-judge',
+    emoji: '⚖️',
+    category: 'Observability',
+    description: 'Run LLM-as-a-judge evaluations on unscored traces for continuous quality feedback',
+    usage: 'construct llm-judge [--limit=N] [--model=NAME]',
+    options: [
+      { flag: '--limit=N', desc: 'Maximum traces to evaluate (default: 10)' },
+      { flag: '--model=NAME', desc: 'LLM model to use for evaluation (default: claude-3-5-sonnet-20241022)' },
+    ],
+  },
+  {
+    name: 'efficiency',
+    emoji: '🧮',
+    category: 'Observability',
+    description: 'Show read efficiency, repeated files, and context-budget guidance',
+    usage: 'construct efficiency [--json]',
+    options: [
+      { flag: '--json', desc: 'Output raw JSON' },
+    ],
   },
   {
     name: 'evals',
     emoji: '🧪',
     category: 'Observability',
+    description: 'Show evaluator catalog for prompt and agent experiments',
+    usage: 'construct evals [--json]',
+    options: [
+      { flag: '--json', desc: 'Output raw JSON' },
+    ],
+  },
+  {
+    name: 'cleanup',
+    emoji: '🧹',
+    category: 'Diagnostics',
+    description: 'Release dev-agent memory pressure by cleaning stale helper and bridge processes',
+    usage: 'construct cleanup [--pressure-release] [--quiet]',
+    options: [
+      { flag: '--pressure-release', desc: 'Also terminate stale cass index processes when swap is above threshold' },
+      { flag: '--quiet', desc: 'Suppress per-process output and only act on the current policy' },
+    ],
+  },
+
+  // ── Teams & Audit ────────────────────────────────────────────────────
+  {
+    name: 'team',
+    emoji: '👥',
+    category: 'Work',
+    description: 'Team review and template listing',
+    usage: 'construct team <review|templates>',
+    subcommands: [
+      { name: 'review',    desc: 'Run telemetry-backed team performance review' },
+      { name: 'templates', desc: 'List available team templates from specialists/teams.json' },
+    ],
+  },
+  {
+    name: 'audit',
+    emoji: '🔍',
+    category: 'Diagnostics',
+    description: 'Audit Construct internals and review the mutation trail',
+    usage: 'construct audit <skills|trail>',
+    subcommands: [
+      { name: 'skills', desc: 'Audit skill files for stub headers, broken references, and missing content' },
+      { name: 'trail',  desc: 'Show the append-only audit trail of every mutation (agent, task, file, hash). Supports --verify, --agent, --tool, --since, --json.' },
+    ],
+  },
+  {
+    name: 'doc',
+    emoji: '🔏',
+    category: 'Diagnostics',
+    description: 'Verify or inspect auditability stamps on Construct-generated markdown files',
+    usage: 'construct doc <verify|install-hooks> [path] [--json]',
+    subcommands: [
+      { name: 'verify',       desc: 'Check body_hash stamps on one file or all .md files under a path. Exits non-zero if any fail.' },
+      { name: 'install-hooks', desc: 'Install the prepare-commit-msg git hook into .git/hooks/ for AI provenance trailers.' },
+    ],
+  },
+   {
+     name: 'bootstrap',
+     emoji: '🌱',
+     category: 'Work',
+     description: 'Import seed observation corpus into local memory store for cold-start acceleration',
+     usage: 'construct bootstrap [--verbose]',
+     options: [
+       { flag: '--verbose', desc: 'Print each observation imported or skipped' },
+     ],
+   },
+   {
+     name: 'reflect',
+     emoji: '🪞',
+     category: 'Work',
+     description: 'Capture improvement feedback from chat session and update Construct core',
+     usage: 'construct reflect [--target=<internal|how-tos|decisions>] [--summary=<text>]',
+     options: [
+       { flag: '--target=<internal|how-tos|decisions>', desc: 'Knowledge subdir to store feedback (default: internal)' },
+       { flag: '--summary=<text>', desc: 'Brief summary of the improvement feedback' },
+     ],
+   },
+  {
+    name: 'memory',
+    emoji: '💡',
+    category: 'Work',
     core: false,
-    description: 'Evaluator catalog',
-    usage: 'construct evals',
+    description: 'Inspect memory layer',
+    usage: 'construct memory stats|consolidate',
   },
   {
-    name: 'llm-judge',
-    emoji: '⚖️',
-    category: 'Observability',
+    name: 'drop',
+    emoji: '📥',
+    category: 'Work',
+    core: false,
+    description: 'Ingest file from Downloads/Desktop',
+    usage: 'construct drop [--list]',
+  },
+  {
+    name: 'wireframe',
+    emoji: '✏️',
+    category: 'Work',
+    core: false,
+    description: 'Generate wireframes from description',
+    usage: 'construct wireframe "<description>"',
+  },
+  {
+    name: 'ollama',
+    emoji: '🦙',
+    category: 'Integrations',
     core: false,
-    description: 'LLM-as-judge evaluations',
-    usage: 'construct llm-judge',
+    description: 'Manage local Ollama models',
+    usage: 'construct ollama status|pull|test',
   },
   
   // ── Advanced (hidden by default) ──────────────────────────────────────
@@ -487,14 +585,6 @@ export const CLI_COMMANDS = [
     description: 'Embed mode management',
     usage: 'construct embed start|stop|status',
   },
-  {
-    name: 'audit',
-    emoji: '🔍',
-    category: 'Advanced',
-    core: false,
-    description: 'Audit Construct internals',
-    usage: 'construct audit skills|trail',
-  },
   {
     name: 'backup',
     emoji: '💾',
@@ -527,14 +617,6 @@ export const CLI_COMMANDS = [
     description: 'Show version',
     usage: 'construct version | construct --version',
   },
-  {
-    name: 'cleanup',
-    emoji: '🧹',
-    category: 'Advanced',
-    core: false,
-    description: 'Clean stale processes',
-    usage: 'construct cleanup',
-  },
   {
     name: 'skills',
     emoji: '🎯',
@@ -559,6 +641,30 @@ export const CLI_COMMANDS = [
     description: 'Audit policy gates',
     usage: 'construct gates:audit',
   },
+  {
+    name: 'policy',
+    emoji: '🔒',
+    category: 'Advanced',
+    core: false,
+    description: 'Show active policy gates with enforcement details',
+    usage: 'construct policy show',
+    options: [
+      { flag: '--json', desc: 'Output as JSON' },
+    ],
+  },
+  {
+    name: 'ci',
+    emoji: '⚙️',
+    category: 'Advanced',
+    core: false,
+    description: 'Local CI mirror: run CI jobs locally or view recent run status',
+    usage: 'construct ci <preview|status|list>',
+    options: [
+      { flag: '--job=<name>', desc: 'Run a single CI job by id or name fragment' },
+      { flag: '--list',       desc: 'List all jobs without running them' },
+      { flag: '--full',       desc: 'Include Docker/Trivy steps (requires Docker daemon)' },
+    ],
+  },
   {
     name: 'provider',
     emoji: '🔌',
@@ -575,6 +681,54 @@ export const CLI_COMMANDS = [
     description: 'Check auth status',
     usage: 'construct auth:status',
   },
+  {
+    name: 'tags',
+    emoji: '🏷',
+    category: 'Work',
+    core: false,
+    description: 'Manage the controlled tag vocabulary (propose, add, deprecate, audit)',
+    usage: 'construct tags <audit|propose|add|deprecate|archive|list|proposed>',
+  },
+  {
+    name: 'scheduler',
+    emoji: '⏰',
+    category: 'Advanced',
+    core: false,
+    description: 'Manage scheduled background jobs (tag-mining, doc-hygiene, skill-rollup)',
+    usage: 'construct scheduler <list|run|runner>',
+  },
+  {
+    name: 'creds',
+    emoji: '🔑',
+    category: 'Integrations',
+    core: false,
+    description: 'Manage provider credentials (set, rotate, revoke, list)',
+    usage: 'construct creds <list|set|rotate|revoke|test>',
+  },
+  {
+    name: 'providers',
+    emoji: '🔌',
+    category: 'Integrations',
+    core: false,
+    description: 'Provider status, circuit-breaker reset, and resource discovery',
+    usage: 'construct providers <status|discover>',
+  },
+  {
+    name: 'workflow',
+    emoji: '🔄',
+    category: 'Work',
+    core: false,
+    description: 'Instantiate workflow templates (PRD-to-review chains, onboarding, handoffs)',
+    usage: 'construct workflow <list|show|new>',
+  },
+  {
+    name: 'telemetry',
+    emoji: '📊',
+    category: 'Observability',
+    core: false,
+    description: 'Query telemetry traces and latency data',
+    usage: 'construct telemetry query <latency|top-slow|errors|trace>',
+  },
 ];
 
 /** Flat list of all top-level command names (for completions). */

package/lib/comment-lint.mjs

@@ -18,7 +18,7 @@ const JS_HEADER_GLOBS = [
   /^lib\/server\//,
   /^lib\/mcp\//,
   /^lib\/metrics\//,
-  /^sync-agents\.mjs$/,
+  /^sync-specialists\.mjs$/,
   /^tests\//,
 ];
 
@@ -61,6 +61,10 @@ function requiresHeader(rel) {
   if (rel.startsWith('lib/server/static/')) {
     return { required: false, type: null };
   }
+  // Exclude test fixture data files — these are project artifacts, not source files.
+  if (rel.startsWith('tests/fixtures/projects/')) {
+    return { required: false, type: null };
+  }
   // Markdown files always get markdown-style headers, even if the directory
   // glob (e.g. ^tests/) primarily targets JS sources. Without this, .md docs
   // co-located with .mjs tests were forced into /** */ format.

package/lib/completions.mjs

@@ -1,7 +1,7 @@
 /**
  * completions.mjs — generates bash and zsh completion scripts for construct.
  *
- * Called by scripts/sync-agents.mjs after each sync.
+ * Called by scripts/sync-specialists.mjs after each sync.
  * Outputs to a platform-appropriate per-user completions directory.
  */
 

package/lib/config/schema.mjs

@@ -6,7 +6,7 @@
  * before npm install completes in some bootstrap paths.
  *
  * Schema v1 covers: alias, deployment, providers, autoEmbed, telemetry.
- * Tier model selection lives in `agents/registry.json` only — this config
+ * Tier model selection lives in `specialists/registry.json` only — this config
  * file is intentionally not a second edit surface for model assignments.
  * Later phases (6, 7b) extend it with `resources` and `costs` blocks
  * without bumping the version — additive keys are allowed.
@@ -22,6 +22,8 @@ export const DEPLOYMENT_MODES = ['solo', 'team', 'enterprise'];
 export const MCP_BROKER_VALUES = ['auto', 'on', 'off'];
 export const DEFAULT_PROFILE_ID = 'rnd';
 
+export const SURFACES = ['claude', 'opencode', 'codex', 'copilot', 'vscode', 'cursor'];
+
 export const DEFAULT_PROJECT_CONFIG = Object.freeze({
   version: CONFIG_SCHEMA_VERSION,
   alias: 'Construct',
@@ -42,6 +44,7 @@ export const DEFAULT_PROJECT_CONFIG = Object.freeze({
     secondary: null,
     perConversationOverride: true,
   }),
+  hosts: Object.freeze(Object.fromEntries(SURFACES.map((s) => [s, Object.freeze({ enabled: true })]))),
   resources: Object.freeze({
     disk: Object.freeze({
       tracesMaxDays: 30,
@@ -98,6 +101,17 @@ export const FIELD_RULES = {
     },
   },
   resources: { type: 'object', required: false },
+  hosts: {
+    type: 'object',
+    required: false,
+    fields: Object.fromEntries(SURFACES.map((s) => [s, {
+      type: 'object',
+      required: false,
+      fields: {
+        enabled: { type: 'boolean', required: false },
+      },
+    }])),
+  },
   costs: {
     type: 'object',
     required: false,