@geraldmaron/construct 1.0.7 → 1.0.8

package/lib/contracts/validate.mjs

@@ -1,17 +1,17 @@
 /**
- * lib/contracts/validate.mjs — Validate agents/contracts.json at sync time + at handoff.
+ * lib/contracts/validate.mjs — Validate specialists/contracts.json at sync time + at handoff.
  *
  * Three validation tiers:
  *   1. Schema shape: contracts.json conforms to contracts.schema.json (minimal
  *      validator — top-level required fields, contract entry required fields).
  *   2. Cross-file refs: every output.schema points to a real file in lib/schemas/,
  *      every producer/consumer name resolves to an agent or persona in
- *      agents/registry.json, every well-known event/intake string is reachable.
+ *      specialists/registry.json, every well-known event/intake string is reachable.
  *   3. Runtime handoff: a single artifact validated against the schema referenced
  *      by a producer→consumer contract, with mustContain post-conditions.
  *
  * Surfaces:
- *   - scripts/sync-agents.mjs invokes validateContractsFile at sync time.
+ *   - scripts/sync-specialists.mjs invokes validateContractsFile at sync time.
  *   - bin/construct lint:contracts invokes the same path in CI.
  *   - workflowContractValidate (runtime) invokes validateHandoff per handoff.
  */
@@ -21,9 +21,9 @@ import { join, dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const REPO_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..', '..');
-const CONTRACTS_PATH = join(REPO_ROOT, 'agents', 'contracts.json');
-const CONTRACTS_SCHEMA_PATH = join(REPO_ROOT, 'agents', 'contracts.schema.json');
-const REGISTRY_PATH = join(REPO_ROOT, 'agents', 'registry.json');
+const CONTRACTS_PATH = join(REPO_ROOT, 'specialists', 'contracts.json');
+const CONTRACTS_SCHEMA_PATH = join(REPO_ROOT, 'specialists', 'contracts.schema.json');
+const REGISTRY_PATH = join(REPO_ROOT, 'specialists', 'registry.json');
 
 const WELL_KNOWN_PRODUCERS = new Set(['user', 'oncall', 'incident-system', '*']);
 const WELL_KNOWN_CONSUMERS = new Set(['user', 'construct']);
@@ -33,7 +33,7 @@ function readJson(path) {
 }
 
 /**
- * Validate agents/contracts.json shape and cross-file references.
+ * Validate specialists/contracts.json shape and cross-file references.
  * Returns { ok, errors[] } — errors is empty on success.
  */
 export function validateContractsFile({ contractsPath, registryPath, repoRoot = REPO_ROOT } = {}) {
@@ -42,9 +42,9 @@ export function validateContractsFile({ contractsPath, registryPath, repoRoot =
   // When repoRoot is supplied but explicit paths are not, derive both from it
   // so test fixtures and the consistency watcher can validate slices in a
   // tmpdir without pointing at the live repo.
-  const cPath = contractsPath || join(repoRoot, 'agents', 'contracts.json');
-  const rPath = registryPath || join(repoRoot, 'agents', 'registry.json');
-  const schemaPath = join(repoRoot, 'agents', 'contracts.schema.json');
+  const cPath = contractsPath || join(repoRoot, 'specialists', 'contracts.json');
+  const rPath = registryPath || join(repoRoot, 'specialists', 'registry.json');
+  const schemaPath = join(repoRoot, 'specialists', 'contracts.schema.json');
 
   if (!existsSync(cPath)) {
     return { ok: false, errors: [`contracts file not found: ${cPath}`] };
@@ -116,13 +116,11 @@ function collectAgentNames(registryPath) {
   if (!existsSync(registryPath)) return names;
   try {
     const registry = readJson(registryPath);
-    for (const a of registry.agents || []) {
-      if (a?.name) names.add(a.name);
-      if (a?.displayName) names.add(a.displayName);
-    }
-    for (const p of registry.personas || []) {
-      if (p?.name) names.add(p.name);
-      if (p?.displayName) names.add(p.displayName);
+    if (registry.orchestrator?.name) names.add(registry.orchestrator.name);
+    if (registry.orchestrator?.displayName) names.add(registry.orchestrator.displayName);
+    for (const s of registry.specialists || []) {
+      if (s?.name) names.add(s.name);
+      if (s?.displayName) names.add(s.displayName);
     }
   } catch { /* fall through with whatever names we collected */ }
   return names;
@@ -321,3 +319,53 @@ export function validatePostconditions({ contract, artifactPath }) {
   }
   return errors;
 }
+
+// Minimum evidence required: either a PR reference (#N or PR #N) or a file
+// reference of the form `path:<line>` or `file:<line>` where line is a number.
+const CLOSE_REASON_PR_PATTERN = /#\d+/;
+const CLOSE_REASON_FILE_PATTERN = /[\w./\\-]+(?:\.(?:mjs|ts|js|tsx|jsx|py|go|rs|java|md|json|yml|yaml)):[0-9]+/i;
+const CLOSE_REASON_MIN_LENGTH = 20;
+
+/**
+ * Validate a beads close reason for evidence quality.
+ *
+ * Returns { ok: boolean, message: string|null }. On failure, `message` describes
+ * what is missing. The caller decides whether to warn or block based on
+ * CONSTRUCT_BEADS_HYGIENE (warn | block). Default behavior is warn.
+ *
+ * A passing reason must:
+ *   - Be at least 20 characters.
+ *   - Contain a PR reference (#N) OR a file:line reference (path.mjs:42).
+ */
+export function validateBeadsCloseReason(reason) {
+  if (!reason || typeof reason !== 'string') {
+    return { ok: false, message: 'Close reason is empty. Add evidence: PR reference (#N) or file:line reference.' };
+  }
+  const trimmed = reason.trim();
+  if (trimmed.length < CLOSE_REASON_MIN_LENGTH) {
+    return { ok: false, message: `Close reason too short (${trimmed.length} chars). Minimum: ${CLOSE_REASON_MIN_LENGTH}. Add evidence.` };
+  }
+  const hasPr = CLOSE_REASON_PR_PATTERN.test(trimmed);
+  const hasFile = CLOSE_REASON_FILE_PATTERN.test(trimmed);
+  if (!hasPr && !hasFile) {
+    return {
+      ok: false,
+      message: `Close reason lacks evidence. Include a PR reference (#N) or a file:line reference (e.g. lib/foo.mjs:42). Got: "${trimmed.slice(0, 80)}"`,
+    };
+  }
+  return { ok: true, message: null };
+}
+
+/**
+ * Apply the beads close-reason policy: warn or block based on
+ * CONSTRUCT_BEADS_HYGIENE env var. Returns exit code (0 = ok, 1 = block).
+ */
+export function applyBeadsHygienePolicy(reason, { stderr = process.stderr } = {}) {
+  const { ok, message } = validateBeadsCloseReason(reason);
+  if (ok) return 0;
+
+  const mode = (process.env.CONSTRUCT_BEADS_HYGIENE || 'warn').toLowerCase();
+  const prefix = mode === 'block' ? '[beads-hygiene] BLOCK' : '[beads-hygiene] WARN';
+  stderr.write(`${prefix}: ${message}\n`);
+  return mode === 'block' ? 1 : 0;
+}

package/lib/distill.mjs

@@ -11,6 +11,7 @@ import { join, extname, relative, dirname, basename } from 'path';
 import { execSync, spawnSync } from 'child_process';
 import { homedir } from 'os';
 import { getActiveOverlays } from './headhunt.mjs';
+import { withGenAiSpan, GenAiAttrs } from './telemetry/otel-tracer.mjs';
 import {
   EXTRACTABLE_DOCUMENT_EXTS,
   UTF8_TEXT_EXTS,
@@ -355,10 +356,27 @@ export async function distill(dir, { format = 'summary', query = '', mode = 'aut
   }
 
   process.stderr.write('   Invoking claude --print …\n\n');
-  const result = spawnSync('claude', ['--print', prompt], {
-    encoding: 'utf8',
-    maxBuffer: 10 * 1024 * 1024,
-    timeout: 120_000,
+  const result = await withGenAiSpan('chat', {
+    [GenAiAttrs.SYSTEM]: 'anthropic',
+    [GenAiAttrs.OPERATION_NAME]: 'chat',
+    [GenAiAttrs.REQUEST_MODEL]: process.env.CONSTRUCT_MODEL || 'claude-3-5-sonnet',
+    'construct.operation': 'distill',
+    'construct.prompt_chars': prompt.length,
+  }, async (span) => {
+    const r = spawnSync('claude', ['--print', prompt], {
+      encoding: 'utf8',
+      maxBuffer: 10 * 1024 * 1024,
+      timeout: 120_000,
+    });
+    if (r.error) throw r.error;
+    if (r.status !== 0) {
+      const errOut = r.stderr || '';
+      if (errOut) process.stderr.write(`${errOut}\n`);
+      throw new Error(`claude exited with status ${r.status}`);
+    }
+    const out = r.stdout || '';
+    span.setAttribute(GenAiAttrs.USAGE_OUTPUT_TOKENS, Math.ceil(out.length / 4));
+    return r;
   });
 
   if (result.error) throw result.error;

package/lib/doc-stamp.mjs

@@ -7,6 +7,7 @@
  *   stampFrontmatter  — inject/update audit block at top of a markdown string
  *   verifyStamp       — verify body_hash against current content
  *   parseStamp        — extract stamp fields from a document string
+ *   validateTags      — validate frontmatter tags against a loaded vocabulary
  *
  * Design:
  *   - Zero npm dependencies (Node built-ins only)
@@ -16,9 +17,12 @@
  *     trimmed, so whitespace-only edits do not break verification.
  *   - generator field is intentionally short (no version pinning) so the
  *     stamp survives construct upgrades without false-positive hash mismatches.
+ *   - validateTags does NOT throw: it returns { errors, warnings } for callers
+ *     to decide how to handle violations.
  */
 
 import { createHash, randomBytes } from 'node:crypto';
+import { validateTags as vocabValidateTags, isTagDeprecated, isTagArchived } from './tags/vocabulary.mjs';
 
 // ---------------------------------------------------------------------------
 // UUIDv7 — RFC 9562 §5.7
@@ -147,6 +151,50 @@ export function parseStamp(content) {
   return fields;
 }
 
+// ---------------------------------------------------------------------------
+// Tag validation — uses vocabulary module, returns errors/warnings for callers
+// ---------------------------------------------------------------------------
+
+/**
+ * Validates frontmatter tags against a loaded vocabulary object.
+ * Returns { errors: string[], warnings: string[] }.
+ *
+ * Errors (hard violations):
+ *   - Two or more tags from the same exclusive facet (duplicateFacets)
+ *   - Writing a tag with status 'archived'
+ *
+ * Warnings (soft violations):
+ *   - Tag ID not found in vocabulary (unknown)
+ *   - Writing a tag with status 'deprecated'
+ */
+export function validateTags(frontmatter, vocab) {
+  const tags = Array.isArray(frontmatter.tags) ? frontmatter.tags : [];
+  const errors = [];
+  const warnings = [];
+
+  if (tags.length === 0) return { errors, warnings };
+
+  const { unknown, duplicateFacets } = vocabValidateTags(tags, vocab);
+
+  for (const id of duplicateFacets) {
+    errors.push(`exclusive-facet violation: tag "${id}" shares a facet with an earlier tag`);
+  }
+
+  for (const id of unknown) {
+    warnings.push(`unknown tag: "${id}" is not in the controlled vocabulary`);
+  }
+
+  for (const id of tags) {
+    if (isTagArchived(id, vocab)) {
+      errors.push(`archived-tag write: tag "${id}" has status archived and must not be applied`);
+    } else if (isTagDeprecated(id, vocab)) {
+      warnings.push(`deprecated-tag write: tag "${id}" has status deprecated`);
+    }
+  }
+
+  return { errors, warnings };
+}
+
 /**
  * Verify that the stored body_hash matches the current body.
  * Returns { valid: true } or { valid: false, reason, stored, computed }.

package/lib/doctor/watchers/consistency.mjs

@@ -7,11 +7,11 @@
  *   2. MCP registration ↔ impl: every `name === '<tool>'` branch in the MCP
  *      dispatch resolves to an imported function, and every exported tool
  *      function in lib/mcp/tools/*.mjs is wired into the dispatch.
- *   3. Roles ↔ registry: every persona key in agents/role-manifests.json
- *      resolves to a persona or agent name in agents/registry.json.
+ *   3. Roles ↔ registry: every persona key in specialists/role-manifests.json
+ *      resolves to a persona or agent name in specialists/registry.json.
  *   4. Persona promptFiles: every registry.personas[].promptFile and
  *      registry.agents[].promptFile exists on disk.
- *   5. Contracts ↔ schemas: agents/contracts.json passes validateContractsFile
+ *   5. Contracts ↔ schemas: specialists/contracts.json passes validateContractsFile
  *      (cross-file refs, producer/consumer names, schema paths).
  *
  * Each violation produces an audit record. Blocking severity escalates to a
@@ -21,6 +21,7 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
 import { join, dirname, resolve } from 'node:path';
+import os from 'node:os';
 import { fileURLToPath } from 'node:url';
 
 import { record } from '../audit.mjs';
@@ -61,7 +62,7 @@ export async function tick() {
 }
 
 /**
- * Run all five consistency checks. Returns { findings: [], passed: [] }.
+  * Run all six consistency checks. Returns { findings: [], passed: [] }.
  * Pure function — no audit/escalate side effects. Surfaced separately so the
  * `construct doctor consistency` CLI and the release-gate functional test can
  * call it without spinning up the daemon.
@@ -85,6 +86,9 @@ export async function runAllChecks({ repoRoot = REPO_ROOT } = {}) {
   const contracts = await checkContractsDrift({ repoRoot });
   collect(contracts, findings, passed, 'contracts-drift');
 
+  const hosts = checkHostSurfaces({ repoRoot });
+  collect(hosts, findings, passed, 'host-surfaces');
+
   return { findings, passed };
 }
 
@@ -219,8 +223,8 @@ function camelToSnake(s) {
 
 function checkRolesDrift({ repoRoot }) {
   const violations = [];
-  const manifestsPath = join(repoRoot, 'agents', 'role-manifests.json');
-  const registryPath = join(repoRoot, 'agents', 'registry.json');
+  const manifestsPath = join(repoRoot, 'specialists', 'role-manifests.json');
+  const registryPath = join(repoRoot, 'specialists', 'registry.json');
 
   if (!existsSync(manifestsPath) || !existsSync(registryPath)) {
     return { summary: 'role manifests or registry missing', violations: [] };
@@ -230,11 +234,12 @@ function checkRolesDrift({ repoRoot }) {
   const registry = JSON.parse(readFileSync(registryPath, 'utf8'));
 
   const known = new Set();
-  for (const a of registry.agents || []) {
-    if (a?.name) { known.add(a.name); known.add(`cx-${a.name}`); }
+  for (const s of registry.specialists || []) {
+    if (s?.name) { known.add(s.name); known.add(`cx-${s.name}`); }
   }
-  for (const p of registry.personas || []) {
-    if (p?.name) { known.add(p.name); known.add(`cx-${p.name}`); }
+  if (registry.orchestrator?.name) {
+    known.add(registry.orchestrator.name);
+    known.add(`cx-${registry.orchestrator.name}`);
   }
 
   const personaKeys = Object.keys(manifests.personas || manifests || {});
@@ -257,13 +262,16 @@ function checkRolesDrift({ repoRoot }) {
 
 function checkPersonaPrompts({ repoRoot }) {
   const violations = [];
-  const registryPath = join(repoRoot, 'agents', 'registry.json');
+  const registryPath = join(repoRoot, 'specialists', 'registry.json');
   if (!existsSync(registryPath)) return { summary: 'registry missing', violations: [] };
 
   const registry = JSON.parse(readFileSync(registryPath, 'utf8'));
   let checked = 0;
 
-  for (const list of [registry.personas || [], registry.agents || []]) {
+  for (const list of [
+    registry.orchestrator ? [registry.orchestrator] : [],
+    registry.specialists || [],
+  ]) {
     for (const entry of list) {
       const ref = entry?.promptFile;
       if (!ref) continue;
@@ -308,3 +316,45 @@ async function checkContractsDrift({ repoRoot }) {
   }
   return { summary: `contracts: ${violations.length} drift`, violations };
 }
+
+// ── Check 6: host surfaces ─────────────────────────────────────────────────
+
+function getVSCodeSettingsDir(homeDir) {
+  const platform = os.platform();
+  if (platform === 'darwin') return join(homeDir, 'Library', 'Application Support', 'Code', 'User');
+  if (platform === 'linux') return join(homeDir, '.config', 'Code', 'User');
+  const appData = process.env.APPDATA ?? join(homeDir, 'AppData', 'Roaming');
+  return join(appData, 'Code', 'User');
+}
+
+function checkHostSurfaces({ repoRoot }) {
+  const violations = [];
+  const homeDir = os.homedir();
+  const surfaces = [
+    { id: 'claude', label: 'Claude Code', check: () => existsSync(join(homeDir, '.claude', 'agents')) },
+    { id: 'opencode', label: 'OpenCode', check: () => existsSync(join(homeDir, '.config', 'opencode', 'opencode.json')) },
+    { id: 'codex', label: 'Codex', check: () => existsSync(join(homeDir, '.codex', 'agents')) },
+    { id: 'copilot', label: 'Copilot', check: () => existsSync(join(homeDir, '.github', 'prompts')) },
+    { id: 'vscode', label: 'VS Code', check: () => existsSync(join(getVSCodeSettingsDir(homeDir), 'settings.json')) },
+    { id: 'cursor', label: 'Cursor', check: () => existsSync(join(homeDir, '.cursor', 'mcp.json')) },
+  ];
+
+  const absent = surfaces.filter((s) => !s.check());
+  if (absent.length > 0) {
+    for (const s of absent) {
+      violations.push({
+        category: 'host-surfaces',
+        severity: 'advisory',
+        target: s.id,
+        summary: `Host surface '${s.label}' config not found — run \`construct sync\` to set up adapters`,
+      });
+    }
+    violations.push({
+      category: 'host-surfaces',
+      severity: 'advisory',
+      summary: `${absent.length}/${surfaces.length} host surfaces absent: ${absent.map((s) => s.id).join(', ')}`,
+    });
+  }
+
+  return { summary: `host-surfaces: ${surfaces.length - absent.length}/${surfaces.length} present`, violations };
+}