@geraldmaron/construct 1.0.0

package/commands/work/parallel-review.md

@@ -0,0 +1,40 @@
+<!--
+commands/work/parallel-review.md — Adversarial parallel review — 5 reviewers must agree before output ships
+
+Adversarial parallel review — 5 reviewers must agree before output ships
+-->
+---
+description: Adversarial parallel review — 5 reviewers must agree before output ships
+---
+
+You are Construct running a parallel adversarial review of: $ARGUMENTS
+
+Dispatch the following 5 review roles concurrently:
+
+1. **cx-reviewer** — Correctness and logic: does it do what it claims? Are there off-by-ones, edge cases, or control flow bugs?
+2. **cx-security** — Vulnerabilities and data exposure: injection, auth bypass, secret leakage, SSRF, unvalidated input
+3. **cx-qa** — Test coverage and edge cases: what's untested? What inputs would break this?
+4. **cx-devil-advocate** — Assumption stress-test: what are we assuming that could be wrong? What failure modes are unaddressed?
+5. **cx-accessibility** (UI changes) or **cx-trace-reviewer** (non-UI) — Inclusive UX or performance bottlenecks
+
+## Merge Gate
+
+All 5 roles must return **PASS** before output ships.
+
+| Finding severity | Action |
+|---|---|
+| CRITICAL | Blocks merge. Must fix before proceeding. |
+| HIGH | Blocks merge. Must fix before proceeding. |
+| MEDIUM | Requires explicit acknowledgment. Document why it's acceptable or fix it. |
+| LOW | Informational only. No action required. |
+
+## Output Format
+
+For each role:
+```
+[ROLE] PASS | FAIL
+Findings:
+- [severity] description
+```
+
+Final verdict: **MERGE READY** or **BLOCKED** (list blocking findings)

package/db/migrations/001_init.sql

@@ -0,0 +1,38 @@
+create table if not exists construct_documents (
+  id text primary key,
+  project text not null,
+  kind text not null,
+  title text not null,
+  summary text,
+  body text not null,
+  source_path text,
+  tags jsonb not null default '[]'::jsonb,
+  content_hash text not null,
+  updated_at timestamptz not null default now(),
+  created_at timestamptz not null default now()
+);
+
+create index if not exists construct_documents_project_kind_idx on construct_documents (project, kind);
+create index if not exists construct_documents_content_hash_idx on construct_documents (content_hash);
+
+create table if not exists construct_embeddings (
+  document_id text primary key references construct_documents(id) on delete cascade,
+  model text not null,
+  embedding double precision[] not null,
+  content_hash text not null,
+  updated_at timestamptz not null default now(),
+  created_at timestamptz not null default now()
+);
+
+create index if not exists construct_embeddings_model_idx on construct_embeddings (model);
+
+create table if not exists construct_sync_runs (
+  id bigserial primary key,
+  project text not null,
+  source text not null,
+  documents_synced integer not null default 0,
+  embeddings_synced integer not null default 0,
+  status text not null,
+  note text,
+  created_at timestamptz not null default now()
+);

package/langfuse/docker-compose.yml

@@ -0,0 +1,82 @@
+# Construct — Langfuse Self-Hosted
+# Auto-provisioned: keys are seeded at container startup via LANGFUSE_INIT_* vars.
+# No browser setup required. 'construct setup' writes keys to .env automatically.
+#
+# Manual usage:
+#   docker-compose -f langfuse/docker-compose.yml -p construct-langfuse up -d
+#   # Keys are ready immediately — see LANGFUSE_INIT_PROJECT_* below
+
+name: construct-langfuse
+
+services:
+  langfuse-server:
+    image: langfuse/langfuse:2
+    container_name: construct-langfuse
+    restart: unless-stopped
+    depends_on:
+      langfuse-db:
+        condition: service_healthy
+    ports:
+      - "3000:3000"
+    environment:
+      DATABASE_URL: postgresql://langfuse:langfuse@langfuse-db:5432/langfuse
+      NEXTAUTH_SECRET: ${LANGFUSE_NEXTAUTH_SECRET:-construct-nextauth-secret}
+      SALT: ${LANGFUSE_SALT:-construct-salt-value}
+      NEXTAUTH_URL: http://localhost:3000
+      TELEMETRY_ENABLED: "false"
+      LANGFUSE_ENABLE_EXPERIMENTAL_FEATURES: "true"
+      AUTH_DISABLE_SIGNUP: "false"
+      # ── Auto-provisioning (no browser setup needed) ──────────────────
+      LANGFUSE_INIT_ORG_ID: "construct-org"
+      LANGFUSE_INIT_ORG_NAME: "Construct"
+      LANGFUSE_INIT_PROJECT_ID: "construct-project"
+      LANGFUSE_INIT_PROJECT_NAME: "Construct"
+      LANGFUSE_INIT_PROJECT_PUBLIC_KEY: "pk-lf-construct-local"
+      LANGFUSE_INIT_PROJECT_SECRET_KEY: "sk-lf-construct-local"
+      LANGFUSE_INIT_USER_EMAIL: "admin@construct.local"
+      LANGFUSE_INIT_USER_NAME: "Admin"
+      LANGFUSE_INIT_USER_PASSWORD: "construct-admin"
+    healthcheck:
+      test: ["CMD-SHELL", "curl -sf http://localhost:3000/api/public/health || exit 1"]
+      interval: 10s
+      timeout: 5s
+      retries: 10
+      start_period: 30s
+
+  langfuse-db:
+    image: postgres:15-alpine
+    container_name: construct-langfuse-db
+    restart: unless-stopped
+    environment:
+      POSTGRES_USER: langfuse
+      POSTGRES_PASSWORD: langfuse
+      POSTGRES_DB: langfuse
+    volumes:
+      - langfuse_db_data:/var/lib/postgresql/data
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U langfuse -d langfuse"]
+      interval: 3s
+      timeout: 3s
+      retries: 10
+
+  dspy-optimizer:
+    build:
+      context: ./dspy-optimizer
+      dockerfile: Dockerfile
+    container_name: construct-dspy-optimizer
+    restart: "no"
+    profiles:
+      - optimize
+    env_file:
+      - ../.env
+    environment:
+      LANGFUSE_BASEURL: http://langfuse-server:3000
+    depends_on:
+      langfuse-server:
+        condition: service_healthy
+    volumes:
+      - ../.cx:/app/.cx
+
+volumes:
+  langfuse_db_data:
+    driver: local

package/lib/audit-skills.mjs

@@ -0,0 +1,118 @@
+/**
+ * lib/audit-skills.mjs — Audit agent↔skill bindings for orphans and missing files.
+ *
+ * Reports: (a) skills with no agent owner, (b) agents with no skill bindings,
+ * (c) skill paths declared in registry but missing on disk.
+ * Called by 'construct audit skills' and incorporated into 'construct doctor'.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+function findConstructRoot(startPath = process.cwd()) {
+  let current = path.resolve(startPath);
+  while (true) {
+    if (fs.existsSync(path.join(current, 'agents', 'registry.json'))) return current;
+    const parent = path.dirname(current);
+    if (parent === current) return path.resolve(startPath);
+    current = parent;
+  }
+}
+
+function collectSkillFiles(skillsDir) {
+  const results = new Set();
+  function walk(dir, prefix = '') {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+      if (entry.isDirectory()) {
+        walk(path.join(dir, entry.name), prefix ? `${prefix}/${entry.name}` : entry.name);
+      } else if (entry.name.endsWith('.md') && entry.name !== 'routing.md') {
+        const rel = prefix ? `${prefix}/${entry.name.replace(/\.md$/, '')}` : entry.name.replace(/\.md$/, '');
+        results.add(rel);
+      }
+    }
+  }
+  try { walk(skillsDir); } catch { /* skills dir missing */ }
+  return results;
+}
+
+export function auditSkills({ rootDir, silent = false } = {}) {
+  const root = rootDir ?? findConstructRoot();
+  const registryPath = path.join(root, 'agents', 'registry.json');
+  const skillsDir = path.join(root, 'skills');
+
+  const registry = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+  const allSkillFiles = collectSkillFiles(skillsDir);
+
+  const declaredSkills = new Set();
+  const agentsWithNoSkills = [];
+  const missingSkillFiles = [];
+
+  for (const agent of registry.agents ?? []) {
+    const skills = agent.skills ?? [];
+    if (skills.length === 0) {
+      agentsWithNoSkills.push(agent.name);
+    }
+    for (const skill of skills) {
+      declaredSkills.add(skill);
+      if (!allSkillFiles.has(skill)) {
+        missingSkillFiles.push({ agent: agent.name, skill });
+      }
+    }
+  }
+
+  const orphanSkills = [...allSkillFiles].filter((s) => !declaredSkills.has(s));
+
+  const issues = [];
+  if (agentsWithNoSkills.length > 0) issues.push({ kind: 'agents-no-skills', items: agentsWithNoSkills });
+  if (orphanSkills.length > 0) issues.push({ kind: 'orphan-skills', items: orphanSkills });
+  if (missingSkillFiles.length > 0) issues.push({ kind: 'missing-skill-files', items: missingSkillFiles });
+
+  if (!silent) {
+    const line = (msg) => process.stdout.write(`${msg}\n`);
+    line('Construct Skill Audit');
+    line('═════════════════════');
+    line('');
+
+    if (agentsWithNoSkills.length === 0) {
+      line('  ✓ All agents have at least one skill binding');
+    } else {
+      line(`  ⚠ Agents with no skill bindings (${agentsWithNoSkills.length}):`);
+      for (const n of agentsWithNoSkills) line(`      - cx-${n}`);
+    }
+    line('');
+
+    if (orphanSkills.length === 0) {
+      line('  ✓ All skills have at least one agent owner');
+    } else {
+      line(`  ⚠ Skills with no agent owner (${orphanSkills.length}):`);
+      for (const s of orphanSkills) line(`      - skills/${s}.md`);
+    }
+    line('');
+
+    if (missingSkillFiles.length === 0) {
+      line('  ✓ All declared skill paths exist on disk');
+    } else {
+      line(`  ✗ Declared skills missing on disk (${missingSkillFiles.length}):`);
+      for (const { agent, skill } of missingSkillFiles) line(`      - cx-${agent} → skills/${skill}.md`);
+    }
+    line('');
+
+    const hasErrors = missingSkillFiles.length > 0;
+    const hasWarnings = agentsWithNoSkills.length > 0 || orphanSkills.length > 0;
+    if (hasErrors) line('  Result: FAIL — fix missing skill files before syncing');
+    else if (hasWarnings) line('  Result: WARN — bindings incomplete but system is functional');
+    else line('  Result: PASS');
+  }
+
+  return {
+    agentsWithNoSkills,
+    orphanSkills,
+    missingSkillFiles,
+    pass: missingSkillFiles.length === 0,
+  };
+}
+
+export async function runAuditSkillsCli(args = []) {
+  const rootDir = args.find((a) => a.startsWith('--root='))?.split('=')[1] ?? undefined;
+  const result = auditSkills({ rootDir });
+  if (!result.pass) process.exit(1);
+}

package/lib/auto-docs.mjs

@@ -0,0 +1,293 @@
+/**
+ * lib/auto-docs.mjs — regenerate managed regions in markdown docs and build the MkDocs site tree.
+ *
+ * Managed regions are HTML comment markers in the form:
+ *   <!-- AUTO:region-name -->
+ *   content
+ *   <!-- /AUTO:region-name -->
+ *
+ * Running regenerateDocs() is idempotent. With check:true it returns whether
+ * anything would change without writing files, used by CI to detect drift.
+ *
+ * buildSite() writes site/docs/ from the same sources feeding the AUTO regions
+ * so the GitHub Pages site never drifts from the in-repo markdown.
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync } from 'node:child_process';
+
+import { CLI_COMMANDS_BY_CATEGORY, CATEGORY_ORDER } from './cli-commands.mjs';
+
+// --- region helpers ---
+
+function replaceRegion(content, regionName, newBody) {
+  const open = `<!-- AUTO:${regionName} -->`;
+  const close = `<!-- /AUTO:${regionName} -->`;
+  const before = content.indexOf(open);
+  const after = content.indexOf(close);
+  if (before === -1 || after === -1) return null;
+  return content.slice(0, before + open.length) + '\n' + newBody + '\n' + content.slice(after);
+}
+
+function readFile(p) {
+  try { return fs.readFileSync(p, 'utf8'); } catch { return null; }
+}
+
+function writeIfChanged(filePath, newContent) {
+  const existing = readFile(filePath);
+  if (existing === newContent) return false;
+  fs.writeFileSync(filePath, newContent, 'utf8');
+  return true;
+}
+
+// --- region generators ---
+
+function buildCommandsTable() {
+  const rows = [];
+  for (const category of CATEGORY_ORDER) {
+    const cmds = CLI_COMMANDS_BY_CATEGORY[category] ?? [];
+    if (!cmds.length) continue;
+    rows.push(`### ${category}\n`);
+    rows.push('| Command | What it does |');
+    rows.push('|---|---|');
+    for (const cmd of cmds) {
+      rows.push(`| \`construct ${cmd.name}\` | ${cmd.description} |`);
+    }
+    rows.push('');
+  }
+  return rows.join('\n').trimEnd();
+}
+
+function buildCoreDocsContract() {
+  return [
+    '## Required core documents',
+    '',
+    '| File | Purpose | Update when |',
+    '|---|---|---|',
+    '| `.cx/context.md` | Human-readable resumable project context | Active work, decisions, architecture assumptions, or open questions change |',
+    '| `.cx/context.json` | Machine-readable resumable context | Context state needs to stay in sync with `.cx/context.md` |',
+    '| `.cx/workflow.json` | Canonical workflow/task state | Non-trivial work starts, changes phase, or completes |',
+    '| `docs/README.md` | Docs index and maintenance contract | Core docs set or maintenance expectations change |',
+    '| `docs/architecture.md` | Canonical architecture and invariants | Runtime shape, contracts, boundaries, or major dependencies change |',
+    '',
+    'All LLMs working in the repo, including Construct, must read these as project state and keep them current when work changes project reality.',
+  ].join('\n');
+}
+
+const DIR_DESCRIPTIONS = {
+  agents: 'Registry and generated platform adapter chains',
+  bin: 'CLI entrypoint (`construct`)',
+  claude: 'Claude Code integration (agents, settings template)',
+  commands: 'Command prompt assets',
+  codex: 'GitHub Copilot / Codex integration',
+  docs: 'Architecture notes, runbooks, and documentation contract',
+  langfuse: 'Langfuse trace backend for agent observability',
+  lib: 'Core runtime: CLI, hooks, MCP, status, sync, workflow',
+  opencode: 'OpenCode integration config',
+  personas: 'Persona prompt definitions',
+  rules: 'Coding and quality standards',
+  site: 'MkDocs source for the GitHub Pages documentation site',
+  skills: 'Reusable domain knowledge files',
+  tests: 'Test suite',
+};
+
+function buildStructureSection(rootDir) {
+  let trackedDirs;
+  try {
+    const out = execSync('git ls-tree --name-only HEAD', { cwd: rootDir, encoding: 'utf8' });
+    trackedDirs = new Set(out.trim().split('\n').filter(Boolean));
+  } catch {
+    trackedDirs = null;
+  }
+  const entries = fs.readdirSync(rootDir, { withFileTypes: true })
+    .filter(e => e.isDirectory() && !e.name.startsWith('.') && e.name !== 'node_modules' && (trackedDirs === null || trackedDirs.has(e.name)))
+    .sort((a, b) => a.name.toLowerCase().localeCompare(b.name.toLowerCase()));
+
+  const lines = ['```text', 'construct/'];
+  for (const entry of entries) {
+    const desc = DIR_DESCRIPTIONS[entry.name] ?? '';
+    lines.push(`├── ${entry.name.padEnd(16)} ${desc}`.trimEnd());
+  }
+  lines.push('```');
+  return lines.join('\n');
+}
+
+function extractHookSummary(hookPath) {
+  try {
+    const src = fs.readFileSync(hookPath, 'utf8');
+    const match = src.match(/\/\*\*[\s\S]*?\*\//);
+    if (!match) return '';
+    const block = match[0].replace(/^\/\*\*|\*\/$/g, '').trim();
+    const lines = block.split('\n').map(l => l.replace(/^\s*\*\s?/, '').trim());
+    const purposeLine = lines.find(l => l.includes('—'));
+    if (purposeLine) {
+      const idx = purposeLine.indexOf('—');
+      return purposeLine.slice(idx + 1).trim();
+    }
+    return lines.find(l => l.length > 0) ?? '';
+  } catch { return ''; }
+}
+
+function buildHooksTable(rootDir) {
+  const hooksDir = path.join(rootDir, 'lib', 'hooks');
+  const files = fs.readdirSync(hooksDir)
+    .filter(f => f.endsWith('.mjs'))
+    .sort();
+
+  const rows = ['| Hook | Description |', '|---|---|'];
+  for (const f of files) {
+    const name = f.replace(/\.mjs$/, '');
+    const desc = extractHookSummary(path.join(hooksDir, f));
+    rows.push(`| \`${name}\` | ${desc} |`);
+  }
+  return rows.join('\n');
+}
+
+function buildAgentsTable(rootDir) {
+  const registryPath = path.join(rootDir, 'agents', 'registry.json');
+  let registry;
+  try { registry = JSON.parse(fs.readFileSync(registryPath, 'utf8')); } catch { return ''; }
+
+  const agents = registry.agents ?? registry;
+  if (!Array.isArray(agents)) return '';
+
+  const rows = ['| Agent | Tier | Purpose |', '|---|---|---|'];
+  for (const agent of agents.slice(0, 30)) {
+    const name = agent.id ?? agent.name ?? '—';
+    const tier = agent.tier ?? agent.model_tier ?? '—';
+    const purpose = (agent.description ?? agent.purpose ?? '').split('\n')[0].slice(0, 80);
+    rows.push(`| \`${name}\` | ${tier} | ${purpose} |`);
+  }
+  if (agents.length > 30) rows.push(`| *(+${agents.length - 30} more)* | | |`);
+  return rows.join('\n');
+}
+
+// --- public API ---
+
+/**
+ * Regenerate all AUTO regions in README.md and docs/README.md/docs/architecture.md.
+ * Returns { changed: string[], checked: boolean }.
+ * With check:true writes nothing and sets changed to files that would differ.
+ */
+export async function regenerateDocs({ rootDir, check = false } = {}) {
+  rootDir = rootDir ?? process.cwd();
+  const changed = [];
+
+  const jobs = [
+    {
+      file: path.join(rootDir, 'README.md'),
+      regions: {
+        commands: buildCommandsTable(),
+        structure: buildStructureSection(rootDir),
+        hooks: buildHooksTable(rootDir),
+      },
+    },
+    {
+      file: path.join(rootDir, 'docs', 'architecture.md'),
+      regions: {
+        agents: buildAgentsTable(rootDir),
+      },
+    },
+    {
+      file: path.join(rootDir, 'docs', 'README.md'),
+      regions: {
+        'core-docs': buildCoreDocsContract(),
+      },
+    },
+  ];
+
+  for (const { file, regions } of jobs) {
+    let content = readFile(file);
+    if (!content) continue;
+    let modified = false;
+    for (const [regionName, body] of Object.entries(regions)) {
+      if (!body) continue;
+      const updated = replaceRegion(content, regionName, body);
+      if (updated === null) continue;
+      if (updated !== content) {
+        content = updated;
+        modified = true;
+      }
+    }
+    if (!modified) continue;
+    if (check) {
+      changed.push(file);
+    } else {
+      writeIfChanged(file, content);
+      changed.push(file);
+    }
+  }
+
+  return { changed, checked: check };
+}
+
+/**
+ * Write site/docs/ from the same generators feeding the AUTO regions.
+ * Invoked by `construct docs:site` before `mkdocs build`.
+ */
+export async function buildSite({ rootDir } = {}) {
+  rootDir = rootDir ?? process.cwd();
+  const siteDocsDir = path.join(rootDir, 'site', 'docs');
+  fs.mkdirSync(siteDocsDir, { recursive: true });
+  fs.mkdirSync(path.join(siteDocsDir, 'templates'), { recursive: true });
+
+  const readOrEmpty = (p) => readFile(p) ?? '';
+  const writeTransformed = (src, dest, transform = (content) => content) => {
+    const content = readFile(src);
+    if (content) fs.writeFileSync(path.join(siteDocsDir, dest), transform(content));
+  };
+
+  // index.md — strip the "For contributors" section onwards for a user-facing landing
+  const readme = readOrEmpty(path.join(rootDir, 'README.md'));
+  const cutAt = readme.indexOf('## For contributors');
+  const index = cutAt > 0 ? readme.slice(0, cutAt).trimEnd() + '\n' : readme;
+  fs.writeFileSync(path.join(siteDocsDir, 'index.md'), index);
+
+  // commands.md — full CLI reference
+  const cmdLines = [
+    '<!--\nsite/docs/commands.md — full CLI reference, generated by construct docs:site.\nSource: lib/cli-commands.mjs\n-->\n',
+    '# Command reference\n',
+    buildCommandsTable(),
+  ];
+  fs.writeFileSync(path.join(siteDocsDir, 'commands.md'), cmdLines.join('\n'));
+
+  // hooks.md
+  const hooksLines = [
+    '<!--\nsite/docs/hooks.md — hook reference, generated by construct docs:site.\nSource: lib/hooks/\n-->\n',
+    '# Hooks reference\n',
+    'Hooks run in every Claude Code session. They are registered in `claude/settings.template.json`.\n',
+    buildHooksTable(rootDir),
+  ];
+  fs.writeFileSync(path.join(siteDocsDir, 'hooks.md'), hooksLines.join('\n'));
+
+  // agents.md
+  const agentsTable = buildAgentsTable(rootDir);
+  if (agentsTable) {
+    const agentLines = [
+      '<!--\nsite/docs/agents.md — agent reference, generated by construct docs:site.\nSource: agents/registry.json\n-->\n',
+      '# Agent reference\n',
+      agentsTable,
+    ];
+    fs.writeFileSync(path.join(siteDocsDir, 'agents.md'), agentLines.join('\n'));
+  }
+
+  // copy static docs
+  for (const [src, dest] of [
+    [path.join(rootDir, 'docs', 'architecture.md'), 'architecture.md'],
+    [path.join(rootDir, 'CONTRIBUTING.md'), 'contributing.md'],
+    [path.join(rootDir, 'CLAUDE.md'), 'claude.md'],
+  ]) {
+    const content = readFile(src);
+    if (!content) continue;
+    const transformed = dest === 'contributing.md'
+      ? content.replaceAll('[CLAUDE.md](CLAUDE.md)', '[CLAUDE.md](claude.md)')
+      : dest === 'claude.md'
+        ? content.replaceAll('[docs/templates/README.md](docs/templates/README.md)', '[docs/templates/README.md](templates/README.md)')
+        : content;
+    fs.writeFileSync(path.join(siteDocsDir, dest), transformed);
+  }
+
+  writeTransformed(path.join(rootDir, 'docs', 'templates', 'README.md'), path.join('templates', 'README.md'));
+
+}