@geraldmaron/construct 1.0.14 → 1.0.16

package/lib/sync/skill-frontmatter.mjs

@@ -2,38 +2,130 @@
  * lib/sync/skill-frontmatter.mjs — Build Anthropic Agent Skills frontmatter
  * for SKILL.md files emitted by sync-specialists.
  *
- * Anthropic Skills require YAML frontmatter with at minimum `name` and
- * `description`. The description gates skill selection — without it, the
- * loader silently skips the file (the user-reported bug: 141 files dropped).
- * Source Construct skills carry an HTML comment header with the description;
- * extractSkillDescription pulls it out.
+ * Source skills carry YAML frontmatter with at minimum `name` + `description`
+ * (Anthropic spec). For role files, extra construct-internal keys (role,
+ * applies_to, inherits, version, profiles, cap) live in the same block; sync
+ * drops those at emit time so only spec-compliant keys ship in SKILL.md.
  *
- * Also exports a conservative stripLeadingFrontmatter helper so we never
- * emit double-frontmatter when the source body already has its own block.
+ * Backwards-compat path: source files missing YAML frontmatter fall through
+ * to HTML-comment preamble extraction, then first body paragraph. Keeps
+ * unmigrated files working during transition; the validator warns until
+ * they migrate.
+ *
+ * Zero-dep posture: runs from isolated environments (cpSync'd tmpdirs
+ * without node_modules), so the YAML reader/emitter stays in-tree. Surface
+ * is small — read flat top-level keys + simple inline arrays; write 2 keys
+ * (name, description). For richer YAML, the migration script and validator
+ * use js-yaml.
  */
 
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/;
 const HTML_COMMENT_RE = /^<!--([\s\S]*?)-->/;
-// Matches the source skill comment header shape: `skills/path/foo.md (Title)
-// Use when X.\n...rest of comment...`. Group 1 captures the optional title,
-// group 2 captures all subsequent prose inside the comment. No /m flag — `$`
-// matches end of input, not end of line, so multi-line "Use when..." prose
-// is captured in full and firstSentence() picks the first terminator.
-
 const SOURCE_HEADER_RE = /^skills\/[\w./-]+\s*(?:\(([^)]+)\))?\s*([\s\S]*?)$/;
 
-// Anthropic Skills cap descriptions at 1024 chars; this cap is tighter so
-// the YAML stays readable in `construct skills list` output too.
-const DESCRIPTION_MAX = 240;
+const DESCRIPTION_MAX = 1024;
+
+// In-tree minimal YAML parser. Handles the subset Construct skill frontmatter
+// uses: flat scalar keys, double/single-quoted or unquoted strings, simple
+// inline arrays ([a, b, c]), and block-style arrays (- item per line).
+// Unparseable input returns null; callers fall back to extraction.
+
+function parseFlatYaml(text) {
+  if (!text || typeof text !== 'string') return null;
+  const lines = text.split('\n');
+  const out = {};
+  let pendingArrayKey = null;
+  try {
+    for (const raw of lines) {
+      const line = raw.replace(/\r$/, '');
+      if (!line.trim() || line.trim().startsWith('#')) continue;
+      if (pendingArrayKey && /^\s+-\s+/.test(line)) {
+        out[pendingArrayKey].push(parseScalar(line.replace(/^\s+-\s+/, '')));
+        continue;
+      }
+      pendingArrayKey = null;
+      const m = line.match(/^([A-Za-z_][\w-]*)\s*:\s*(.*)$/);
+      if (!m) continue;
+      const key = m[1];
+      const rawValue = m[2];
+      if (rawValue === '' || rawValue === undefined) {
+        out[key] = [];
+        pendingArrayKey = key;
+        continue;
+      }
+      if (rawValue.startsWith('[') && rawValue.endsWith(']')) {
+        const inner = rawValue.slice(1, -1).trim();
+        out[key] = inner === '' ? [] : inner.split(',').map((s) => parseScalar(s.trim()));
+        continue;
+      }
+      out[key] = parseScalar(rawValue);
+    }
+  } catch (err) {
+    if (err instanceof YamlError) return null;
+    throw err;
+  }
+  return out;
+}
+
+class YamlError extends Error {}
+
+function parseScalar(s) {
+  const trimmed = s.trim();
+  if (trimmed === '' || trimmed === 'null' || trimmed === '~') return null;
+  if (trimmed === 'true') return true;
+  if (trimmed === 'false') return false;
+  if (/^-?\d+$/.test(trimmed)) return Number(trimmed);
+  if (/^-?\d+\.\d+$/.test(trimmed)) return Number(trimmed);
+  if (trimmed.startsWith('"')) {
+    if (!trimmed.endsWith('"') || trimmed.length < 2) throw new YamlError('unclosed double quote');
+    return trimmed.slice(1, -1).replace(/\\"/g, '"');
+  }
+  if (trimmed.startsWith("'")) {
+    if (!trimmed.endsWith("'") || trimmed.length < 2) throw new YamlError('unclosed single quote');
+    return trimmed.slice(1, -1).replace(/\\'/g, "'");
+  }
+  return trimmed;
+}
+
+function emitScalar(value) {
+  if (value === null || value === undefined) return 'null';
+  if (typeof value === 'boolean' || typeof value === 'number') return String(value);
+  const s = String(value);
+  if (/[:"'\n#&*!|>%@`]|^[-?]/.test(s) || s.length === 0) {
+    return `"${s.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+  }
+  return s;
+}
+
+export function readSkillFrontmatter(content) {
+  if (!content) return null;
+  const match = content.match(FRONTMATTER_RE);
+  if (!match) return null;
+  return parseFlatYaml(match[1]);
+}
 
 export function buildSkillFrontmatter(name, sourceContent) {
-  const skillName = String(name).replace(/\//g, '.');
-  const description = extractSkillDescription(sourceContent) || `Construct skill: ${skillName}`;
-  const safeDescription = description.replace(/\n+/g, ' ').slice(0, DESCRIPTION_MAX).replace(/"/g, "'");
-  return `---\nname: ${skillName}\ndescription: "${safeDescription}"\n---\n`;
+  const fromSource = readSkillFrontmatter(sourceContent);
+  const skillName = (fromSource?.name && typeof fromSource.name === 'string')
+    ? fromSource.name
+    : kebabFromPath(name);
+  const description = (fromSource?.description && typeof fromSource.description === 'string')
+    ? fromSource.description
+    : (extractSkillDescription(sourceContent) || `Construct skill: ${skillName}`);
+  const safe = description.replace(/\n+/g, ' ').slice(0, DESCRIPTION_MAX).replace(/"/g, "'").trim();
+  return `---\nname: ${emitScalar(skillName)}\ndescription: ${emitScalar(safe)}\n---\n`;
+}
+
+function kebabFromPath(name) {
+  return String(name).replace(/[/.]/g, '-').toLowerCase();
 }
 
 export function extractSkillDescription(content) {
   if (!content) return null;
+  const fromYaml = readSkillFrontmatter(content);
+  if (fromYaml?.description && typeof fromYaml.description === 'string') {
+    return fromYaml.description;
+  }
   const commentMatch = content.match(HTML_COMMENT_RE);
   if (commentMatch) {
     const inner = commentMatch[1].trim();
@@ -45,7 +137,7 @@ export function extractSkillDescription(content) {
     const lines = inner.split('\n').map((l) => l.trim()).filter(Boolean);
     if (lines.length >= 2) return firstSentence(lines.slice(1).join(' '));
   }
-  const body = content.replace(HTML_COMMENT_RE, '').trim();
+  const body = content.replace(FRONTMATTER_RE, '').replace(HTML_COMMENT_RE, '').trim();
   const paragraphs = body.split(/\n\s*\n/);
   for (const p of paragraphs) {
     const trimmed = p.trim();

package/lib/tracking-surfaces.mjs

@@ -26,6 +26,7 @@ import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSy
 import { join } from 'node:path';
 
 import { extractBeadsFromPlan, syncPlanWithBeads } from './beads-automation.mjs';
+import { assertBeadId } from './beads-client.mjs';
 import { buildPlanTemplate } from './project-init-shared.mjs';
 
 const CONTEXT_RECENT_DAYS = 30;
@@ -191,6 +192,7 @@ export async function closeBeadsFromPrRefs({ prNumber, mergeCommitSha = '', cwd
     : `Merged via PR #${prNumber}`;
 
   for (const id of beadIds) {
+    try { assertBeadId(id); } catch (err) { errors.push({ id, reason: 'invalid-bead-id', detail: err.message }); continue; }
     const status = readBeadStatus(cwd, id);
     if (status === 'closed') { skipped.push(id); continue; }
     if (status === null) { errors.push({ id, reason: 'bd-show-failed' }); continue; }

package/lib/update.mjs

@@ -10,6 +10,8 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 
+import { writeVersionStamp } from './maintenance/cleanup.mjs';
+
 const PACKAGE_NAME = '@geraldmaron/construct';
 
 function readPackageJson(dir) {
@@ -70,6 +72,15 @@ export function buildUpdatePlan({ cwd }) {
         args: [binPath, 'sync', '--no-docs'],
         cwd: sourceRoot,
       },
+      // Sweep legacy cx-*.md/.toml/.prompt.md left over from older releases
+      // at user scope, so the next doctor doesn't surface the warning.
+      {
+        label: 'Sweep legacy agents at user scope',
+        command: process.execPath,
+        args: [binPath, 'doctor', '--fix-legacy-agents'],
+        cwd: sourceRoot,
+        optional: true,
+      },
       {
         label: 'Run health checks',
         command: process.execPath,
@@ -84,14 +95,24 @@ function formatCommand(command, args) {
   return [command, ...args].join(' ');
 }
 
-function runStep(step, { spawn, env }) {
+function runStep(step, { spawn, env, stdout }) {
   const result = spawn(step.command, step.args, {
     cwd: step.cwd,
     env,
     stdio: 'inherit',
   });
-  if (result?.error) throw result.error;
+  if (result?.error) {
+    if (step.optional) {
+      stdout?.write?.(`  (skipped: ${result.error.message})\n`);
+      return;
+    }
+    throw result.error;
+  }
   if ((result?.status ?? 1) !== 0) {
+    if (step.optional) {
+      stdout?.write?.(`  (skipped: exit ${result?.status ?? 1})\n`);
+      return;
+    }
     throw new Error(`${step.label} failed with exit code ${result.status ?? 1}`);
   }
 }
@@ -107,9 +128,16 @@ export function runUpdate({ cwd, env = process.env, spawn = spawnSync, stdout =
   for (const step of plan.steps) {
     stdout.write(`→ ${step.label}\n`);
     stdout.write(`  ${formatCommand(step.command, step.args)}\n`);
-    runStep(step, { spawn, env });
+    runStep(step, { spawn, env, stdout });
   }
 
+  // Advance the cleanup stamp to the checkout version so the next CLI
+  // invocation doesn't run a full cleanup pass on the assumption that
+  // an upgrade just happened.
+  try {
+    writeVersionStamp({ version: plan.version, summary: { freedBytes: 0, durationMs: 0 } });
+  } catch { /* stamp write is best-effort */ }
+
   stdout.write('\n✓ Construct updated from current checkout.\n');
   return plan;
 }

package/lib/upgrade.mjs

@@ -10,6 +10,8 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
+import { writeVersionStamp } from './maintenance/cleanup.mjs';
+
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT_DIR = path.resolve(__dirname, '..');
 const PACKAGE_NAME = '@geraldmaron/construct';
@@ -97,7 +99,7 @@ export function runUpgrade({ cwd = process.cwd(), env = process.env, stdout = pr
   }
   
   stdout.write('Upgrading...\n\n');
-  
+
   const steps = [
     {
       label: 'Fetching latest from npm',
@@ -109,6 +111,15 @@ export function runUpgrade({ cwd = process.cwd(), env = process.env, stdout = pr
       command: 'construct',
       args: ['sync', '--no-docs'],
     },
+    // Sweep legacy cx-*.md/.toml/.prompt.md left behind by older releases at
+    // user scope. Without this the user gets a doctor warning every session
+    // until they manually run `construct doctor --fix-legacy-agents`.
+    {
+      label: 'Sweeping legacy agents at user scope',
+      command: 'construct',
+      args: ['doctor', '--fix-legacy-agents'],
+      optional: true,
+    },
     {
       label: 'Running health checks',
       command: 'construct',
@@ -123,18 +134,34 @@ export function runUpgrade({ cwd = process.cwd(), env = process.env, stdout = pr
       env,
       stdio: 'inherit',
     });
-    
+
     if (result.error) {
+      if (step.optional) {
+        stdout.write(`  (skipped: ${result.error.message})\n`);
+        continue;
+      }
       stdout.write(`\n✗ ${step.label} failed: ${result.error.message}\n`);
       return { success: false, reason: 'step_failed', step: step.label };
     }
-    
+
     if (result.status !== 0) {
+      if (step.optional) {
+        stdout.write(`  (skipped: exit ${result.status})\n`);
+        continue;
+      }
       stdout.write(`\n✗ ${step.label} failed with exit code ${result.status}\n`);
       return { success: false, reason: 'step_failed', step: step.label };
     }
   }
-  
+
+  // Advance the cleanup stamp so the next CLI invocation doesn't re-run a
+  // full cleanup pass under the assumption that the user just upgraded.
+  // Without this, every command pays the cleanup cost until something
+  // else writes the stamp.
+  try {
+    writeVersionStamp({ version: latestVersion, summary: { freedBytes: 0, durationMs: 0 } });
+  } catch { /* stamp write is best-effort */ }
+
   stdout.write('\n');
   stdout.write(`✓ Upgraded to ${latestVersion}\n`);
   return { success: true, upgraded: true, from: currentVersion, to: latestVersion };

package/lib/validators/skills.mjs

@@ -1,62 +1,71 @@
 /**
  * lib/validators/skills.mjs — Validate the structure of skill files.
  *
- * Skills are markdown files under `skills/` (and any merged plugin or project
- * skill paths) that follow this convention:
+ * After the YAML-frontmatter migration, every skill file under `skills/` has:
  *
- *   <!--
- *   skills/<domain>/<name>.md — <Title> — <one-line description>
- *   ...
- *   -->
+ *   ---
+ *   name: <kebab-case>
+ *   description: "<≤1024 chars, includes a 'use when' trigger>"
+ *   [role/applies_to/inherits/version/profiles/cap for role files]
+ *   ---
  *   # <Title>
- *
- *   Use this skill when <triggering condition>.
- *   ...
+ *   Use when: <trigger condition>
+ *   <body>
  *
  * The validator splits findings into hard errors (block the build) and soft
  * warnings (surfaced by `construct doctor` without failing it):
  *
  *   Hard errors:
- *     - missing H1 title
+ *     - frontmatter missing or not parseable as YAML
+ *     - name missing, > 64 chars, fails ^[a-z0-9][a-z0-9-]*$, or contains
+ *       reserved tokens (anthropic, claude)
+ *     - description missing, empty, > 1024 chars, contains XML/HTML tags,
+ *       or missing a "use when" trigger clause
+ *     - missing H1 title (in body)
  *     - title over 80 chars
  *     - duplicate relative paths across roots
  *     - unreadable file
  *
  *   Soft warnings:
- *     - opener is missing or doesn't match a recognised "Use this skill
- *       when/to/for ..." form (skills with non-trigger openers still load,
- *       but they're harder for routing to surface)
- *     - opener over 240 chars
- *
- * Hard checks prevent broken file structure; soft checks surface drift from
- * authoring conventions without blocking authors who legitimately diverge.
+ *     - body opener missing or doesn't match a "Use this skill when/to/for ..."
+ *       form (YAML description is now primary; body opener is a behavioral hint)
+ *     - body opener over 240 chars
  */
 
 import { readdirSync, readFileSync, statSync } from 'node:fs';
 import path from 'node:path';
+import yaml from 'js-yaml';
 
-const DESCRIPTION_MAX_CHARS = 240;
+const DESCRIPTION_MAX = 1024;
+const NAME_MAX = 64;
 const TITLE_MAX_CHARS = 80;
+const BODY_OPENER_MAX = 240;
+const NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---\n?/;
 
-// Accept any of the conventional skill-trigger openers actually in use across
-// the corpus: "Use this skill when/to/for", "Use when:", "Use this when",
-// "Trigger:", or a leading "When ..." that signals a triggering condition.
 const TRIGGER_PATTERN = /^(?:use\s+(?:this\s+(?:skill\s+)?)?(?:when|to|for|if)\b|when\s+to\s+use\b|trigger\s*:|use\s+when\s*:)/i;
 
 function* walk(root) {
-  const entries = readdirSync(root, { withFileTypes: true });
-  for (const entry of entries) {
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
     const full = path.join(root, entry.name);
-    if (entry.isDirectory()) {
-      yield* walk(full);
-    } else if (entry.isFile() && entry.name.endsWith('.md')) {
-      yield full;
-    }
+    if (entry.isDirectory()) yield* walk(full);
+    else if (entry.isFile() && entry.name.endsWith('.md')) yield full;
+  }
+}
+
+function parseFrontmatter(content) {
+  const match = content.match(FRONTMATTER_RE);
+  if (!match) return { frontmatter: null, body: content };
+  try {
+    const parsed = yaml.load(match[1]) || {};
+    return { frontmatter: parsed, body: content.slice(match[0].length) };
+  } catch (err) {
+    return { frontmatter: null, body: content.slice(match[0].length), yamlError: err.message };
   }
 }
 
-function extractTitleAndOpener(text) {
-  const lines = text.split(/\r?\n/);
+function extractTitleAndOpener(body) {
+  const lines = body.split(/\r?\n/);
   let title = null;
   let opener = null;
   let inBody = false;
@@ -64,11 +73,7 @@ function extractTitleAndOpener(text) {
     const line = lines[i].trim();
     if (!title) {
       const m = line.match(/^#\s+(.+?)\s*$/);
-      if (m) {
-        title = m[1];
-        inBody = true;
-        continue;
-      }
+      if (m) { title = m[1]; inBody = true; continue; }
     } else if (inBody && line && !line.startsWith('#') && !line.startsWith('<!--')) {
       opener = line;
       break;
@@ -77,23 +82,31 @@ function extractTitleAndOpener(text) {
   return { title, opener };
 }
 
-/**
- * Validate every skill file under one or more directories.
- *
- * @param {string[]|string} roots — directories to walk recursively
- * @returns {{
- *   valid: boolean,
- *   errors: string[],
- *   warnings: string[],
- *   skills: Array<{ path: string, title: string|null, opener: string|null }>,
- * }}
- */
+function validateName(name) {
+  if (!name) return 'frontmatter.name is missing';
+  if (typeof name !== 'string') return `frontmatter.name must be a string (got ${typeof name})`;
+  if (!NAME_RE.test(name)) return `frontmatter.name "${name}" must match ${NAME_RE}`;
+  if (name.length > NAME_MAX) return `frontmatter.name "${name}" exceeds ${NAME_MAX} chars`;
+  if (/\banthropic\b|\bclaude\b/.test(name)) return `frontmatter.name "${name}" contains reserved token`;
+  return null;
+}
+
+function validateDescription(description) {
+  if (!description) return 'frontmatter.description is missing or empty';
+  if (typeof description !== 'string') return `frontmatter.description must be a string (got ${typeof description})`;
+  if (description.length > DESCRIPTION_MAX) return `frontmatter.description ${description.length} > ${DESCRIPTION_MAX} chars`;
+  if (/<[A-Za-z][^>]*>/.test(description)) return 'frontmatter.description contains XML/HTML tags';
+  if (!/use\s+when|use\s+this/i.test(description)) return 'frontmatter.description missing "use when" trigger clause';
+  return null;
+}
+
 export function validateSkills(roots) {
   const dirs = Array.isArray(roots) ? roots : [roots];
   const errors = [];
   const warnings = [];
   const skills = [];
   const seenRelative = new Map();
+  const seenNames = new Map();
 
   for (const dir of dirs) {
     let exists = false;
@@ -113,12 +126,31 @@ export function validateSkills(roots) {
 
       let raw;
       try { raw = readFileSync(filePath, 'utf8'); }
-      catch (err) {
-        errors.push(`${rel}: cannot read (${err.message})`);
+      catch (err) { errors.push(`${rel}: cannot read (${err.message})`); continue; }
+
+      const { frontmatter, body, yamlError } = parseFrontmatter(raw);
+
+      if (yamlError) {
+        errors.push(`${rel}: frontmatter YAML parse error — ${yamlError}`);
         continue;
       }
+      if (!frontmatter) {
+        errors.push(`${rel}: missing YAML frontmatter block (---name/description---)`);
+        continue;
+      }
+
+      const nameErr = validateName(frontmatter.name);
+      if (nameErr) errors.push(`${rel}: ${nameErr}`);
+      else {
+        const dupName = seenNames.get(frontmatter.name);
+        if (dupName) errors.push(`${rel}: duplicate frontmatter.name "${frontmatter.name}" (also in ${dupName})`);
+        else seenNames.set(frontmatter.name, rel);
+      }
+
+      const descErr = validateDescription(frontmatter.description);
+      if (descErr) errors.push(`${rel}: ${descErr}`);
 
-      const { title, opener } = extractTitleAndOpener(raw);
+      const { title, opener } = extractTitleAndOpener(body);
 
       if (!title) {
         errors.push(`${rel}: missing H1 title (e.g. "# Skill Name")`);
@@ -127,14 +159,14 @@ export function validateSkills(roots) {
       }
 
       if (!opener) {
-        warnings.push(`${rel}: no trigger opener after the H1 title — routing will have nothing to match`);
+        warnings.push(`${rel}: no trigger opener in body after the H1 — YAML description still primary, but body opener helps in-task behavior`);
       } else if (!TRIGGER_PATTERN.test(opener)) {
-        warnings.push(`${rel}: opener should start with "Use this skill when/to/for ..." (got "${opener.slice(0, 60)}…")`);
-      } else if (opener.length > DESCRIPTION_MAX_CHARS) {
-        warnings.push(`${rel}: opener exceeds ${DESCRIPTION_MAX_CHARS} chars (got ${opener.length})`);
+        warnings.push(`${rel}: body opener should start with "Use this skill when/to/for ..." (got "${opener.slice(0, 60)}…")`);
+      } else if (opener.length > BODY_OPENER_MAX) {
+        warnings.push(`${rel}: body opener exceeds ${BODY_OPENER_MAX} chars (got ${opener.length})`);
       }
 
-      skills.push({ path: rel, title, opener });
+      skills.push({ path: rel, name: frontmatter.name, description: frontmatter.description, title, opener });
     }
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geraldmaron/construct",
-  "version": "1.0.14",
+  "version": "1.0.16",
   "type": "module",
   "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",
   "bin": {
@@ -57,7 +57,6 @@
     "lint:contracts": "node ./bin/construct lint:contracts",
     "lint:agents": "node ./bin/construct lint:agents",
     "build:sea": "esbuild bin/construct --bundle --platform=node --target=node20 --packages=external --outfile=dist/construct-bundle.cjs 2>&1 || (echo 'esbuild not found — install with: npm install -g esbuild' && exit 1)",
-    "lint:prose": "node scripts/lint-prose.mjs",
     "lint:profiles": "node scripts/lint-profiles.mjs",
     "learning:status": "node scripts/learning-status.mjs",
     "lint:templates": "node scripts/lint-commits-pr.mjs",
@@ -73,16 +72,17 @@
     "@huggingface/transformers": "^4.2.0",
     "@modelcontextprotocol/sdk": "^1.12.0",
     "@xenova/transformers": "^2.0.1",
+    "js-yaml": "^4.2.0",
     "node-webvtt": "^1.9.3",
     "postgres": "^3.4.9"
   },
   "optionalDependencies": {
     "@opentelemetry/api": "^1.9.0",
-    "@opentelemetry/sdk-trace-node": "^1.25.0",
+    "@opentelemetry/core": "^1.25.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.52.0",
     "@opentelemetry/resources": "^1.25.0",
-    "@opentelemetry/semantic-conventions": "^1.25.0",
-    "@opentelemetry/core": "^1.25.0"
+    "@opentelemetry/sdk-trace-node": "^1.25.0",
+    "@opentelemetry/semantic-conventions": "^1.25.0"
   },
   "overrides": {
     "express-rate-limit": "8.5.1",

package/personas/construct.md

@@ -1,10 +1,7 @@
-<!--
-personas/construct.md. Construct persona prompt.
-
-Defines the single user-facing AI interface and its session-start behavior,
-routing rules, approval boundaries, and output contract. Loaded by sync-specialists
-and emitted to every supported platform.
--->
+---
+name: construct
+description: Construct persona prompt.
+---
 You are Construct. The user talks only to you; internal routing and specialist dispatch are implementation detail.
 
 **Anti-fabrication contract**: every load-bearing claim cites a verifiable source. Missing source becomes `unknown` or `[unverified]`. Specialists tailor; the persona never weakens. See `rules/common/no-fabrication.md`.
@@ -37,6 +34,8 @@ Execution model:
 
 Devil's advocate is mandatory for new architectural directions, AI/agent workflow changes, security or data-integrity changes, and promoting a temporary capability to persistent.
 
+Orchestrated dispatches emit a task-packet with `goal`, `intent`, `workCategory`, `riskFlags`, `acceptanceCriteria` before naming specialists (`specialists/contracts.json:construct-to-orchestrator`).
+
 ## Gates and contracts (org-in-a-box)
 
 `routeRequest` returns three artifacts; honor all three: