@geraldmaron/construct 1.0.12 → 1.0.15

package/lib/tracking-surfaces.mjs

@@ -0,0 +1,377 @@
+/**
+ * lib/tracking-surfaces.mjs — automated maintenance for project-tracking files.
+ *
+ * Owns WHAT to refresh; the hooks that call these functions own WHEN. Three
+ * surfaces are covered:
+ *
+ *   - `.cx/context.md` + `.cx/context.json` — project state. Refreshed from
+ *     recent observations, commits, and bead state at the end of each
+ *     session via `refreshContextMd()`.
+ *   - `plan.md` — local working plan. Bead-status table synced via
+ *     `syncPlanFile()` (thin wrapper around `syncPlanWithBeads` in
+ *     lib/beads-automation.mjs). When every referenced bead is closed,
+ *     `archivePlanIfLanded()` stamps a landed footer, copies the plan into
+ *     `.cx/handoffs/`, and resets `plan.md` to the standard template.
+ *   - Beads — `closeBeadsFromPrRefs()` parses a merged PR's body for
+ *     `Refs:` / `Closes:` / `Fixes:` lines and closes the named beads with
+ *     a "Merged via PR #N (sha)" reason.
+ *
+ * Every export is best-effort: caught failures degrade to a structured
+ * result object, never throw. Caller hooks log to stderr via logHookFailure
+ * if they care about the failure mode.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
+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;
+const CONTEXT_MAX_ITEMS_PER_SECTION = 10;
+
+const SECTION_HEADERS = {
+  activeWork: '## Active Work',
+  recentDecisions: '## Recent Decisions',
+  architectureNotes: '## Architecture Notes',
+  openQuestions: '## Open Questions',
+};
+
+// ---------------------------------------------------------------------------
+// context.md / context.json refresh
+// ---------------------------------------------------------------------------
+
+/**
+ * Pull recent activity from observations, git, and beads into the managed
+ * sections of `.cx/context.md`. Preserves any non-managed sections the user
+ * has authored. Stamps `.cx/context.json` with the refresh timestamp and
+ * derived counts so a session-start digest can tell when content is fresh.
+ */
+export async function refreshContextMd({ rootDir, now = new Date() } = {}) {
+  if (!rootDir) return { ok: false, reason: 'rootDir-required' };
+  const contextMdPath = join(rootDir, '.cx', 'context.md');
+  const contextJsonPath = join(rootDir, '.cx', 'context.json');
+  if (!existsSync(contextMdPath)) return { ok: false, reason: 'no-context-md' };
+
+  const cutoff = new Date(now.getTime() - CONTEXT_RECENT_DAYS * 24 * 60 * 60 * 1000);
+  const observations = collectRecentObservations(rootDir, cutoff);
+  const commits = collectRecentCommits(rootDir, cutoff);
+  const closedBeads = collectRecentlyClosedBeads(rootDir, cutoff);
+  const openBeads = collectInProgressBeads(rootDir);
+
+  const sections = {
+    activeWork: formatActiveWork(openBeads),
+    recentDecisions: formatRecentDecisions(observations, commits, closedBeads),
+    architectureNotes: formatArchitectureNotes(observations),
+  };
+
+  const before = readFileSync(contextMdPath, 'utf8');
+  const after = rewriteManagedSections(before, sections);
+  if (after !== before) {
+    writeFileSync(contextMdPath, after, 'utf8');
+  }
+
+  const json = readJsonSafe(contextJsonPath) ?? { format: 'json', source: 'construct' };
+  json.lastRefreshAt = now.toISOString();
+  json.activeWork = openBeads.map((b) => ({ id: b.id, title: b.title, status: b.status }));
+  json.recentDecisions = closedBeads.slice(0, CONTEXT_MAX_ITEMS_PER_SECTION).map((b) => ({
+    id: b.id,
+    title: b.title,
+    closedAt: b.closed || b.updated || b.updatedAt,
+  }));
+  json.architectureNotes = observations
+    .filter((o) => o.category === 'architecture' || o.category === 'decision')
+    .slice(0, CONTEXT_MAX_ITEMS_PER_SECTION)
+    .map((o) => ({ summary: o.summary, ts: o.ts }));
+  writeFileSync(contextJsonPath, JSON.stringify(json, null, 2) + '\n', 'utf8');
+
+  return {
+    ok: true,
+    changed: after !== before,
+    counts: {
+      activeWork: openBeads.length,
+      recentDecisions: closedBeads.length,
+      observations: observations.length,
+      commits: commits.length,
+    },
+  };
+}
+
+// ---------------------------------------------------------------------------
+// plan.md sync and archive
+// ---------------------------------------------------------------------------
+
+/**
+ * Run the existing plan↔beads sync. Wrapper so the Stop hook calls one
+ * stable name even if the underlying implementation changes later.
+ */
+export async function syncPlanFile({ rootDir }) {
+  if (!rootDir) return { ok: false, reason: 'rootDir-required' };
+  try {
+    const changed = await syncPlanWithBeads({ cwd: rootDir });
+    return { ok: true, changed };
+  } catch (err) {
+    return { ok: false, reason: 'sync-threw', error: err?.message };
+  }
+}
+
+/**
+ * When every bead referenced in `plan.md` is closed AND the plan has not
+ * been touched in the last hour, stamp a "Landed" footer, copy the plan to
+ * `.cx/handoffs/<date>-plan-landed.md`, and reset `plan.md` to the template.
+ * Otherwise no-op.
+ */
+export async function archivePlanIfLanded({ rootDir, now = new Date() } = {}) {
+  if (!rootDir) return { ok: false, reason: 'rootDir-required' };
+  const planPath = join(rootDir, 'plan.md');
+  if (!existsSync(planPath)) return { ok: false, reason: 'no-plan' };
+
+  let stat;
+  try { stat = statSync(planPath); }
+  catch { return { ok: false, reason: 'stat-failed' }; }
+  const ONE_HOUR_MS = 60 * 60 * 1000;
+  if (now.getTime() - stat.mtimeMs < ONE_HOUR_MS) {
+    return { ok: false, reason: 'plan-recently-touched' };
+  }
+
+  const content = readFileSync(planPath, 'utf8');
+  const beadRefs = extractBeadsFromPlan(content);
+  if (beadRefs.length === 0) return { ok: false, reason: 'no-bead-refs' };
+
+  const uniqueIds = [...new Set(beadRefs.map((b) => b.beadId))];
+  const statuses = uniqueIds.map((id) => readBeadStatus(rootDir, id));
+  if (statuses.some((s) => s !== 'closed')) {
+    return { ok: false, reason: 'beads-still-open' };
+  }
+
+  const handoffsDir = join(rootDir, '.cx', 'handoffs');
+  mkdirSync(handoffsDir, { recursive: true });
+  const date = now.toISOString().slice(0, 10);
+  const archivePath = join(handoffsDir, `${date}-plan-landed.md`);
+  const archiveBody = `# Landed plan — ${date}\n\nBeads closed: ${uniqueIds.join(', ')}\n\nArchived from \`plan.md\` on ${now.toISOString()} by the session-tracking-refresh hook.\n\n---\n\n${content}`;
+  writeFileSync(archivePath, archiveBody, 'utf8');
+
+  writeFileSync(planPath, buildPlanTemplate(), 'utf8');
+
+  return { ok: true, changed: true, archivePath, beadsClosed: uniqueIds };
+}
+
+// ---------------------------------------------------------------------------
+// Bead closure from merged PR
+// ---------------------------------------------------------------------------
+
+const PR_REFS_PATTERN = /(?:Refs|Closes?|Fixes?|Resolves?)\s*:?\s*(?:#?\d+|(?:construct-[a-z0-9]+(?:\s*,\s*construct-[a-z0-9]+)*))/gi;
+const BEAD_ID_PATTERN = /construct-[a-z0-9]+/g;
+
+/**
+ * Parse a merged PR's body for bead references and close each open one.
+ * Idempotent: skips beads already closed. Best-effort: each `bd close`
+ * failure is captured in the result, no throws.
+ *
+ * @returns {Promise<{ ok: boolean, closed: string[], skipped: string[], errors: object[] }>}
+ */
+export async function closeBeadsFromPrRefs({ prNumber, mergeCommitSha = '', cwd = process.cwd() } = {}) {
+  if (!prNumber) return { ok: false, reason: 'pr-number-required', closed: [], skipped: [], errors: [] };
+
+  const body = readPrBody(prNumber, cwd);
+  if (!body) return { ok: false, reason: 'pr-body-unavailable', closed: [], skipped: [], errors: [] };
+
+  const beadIds = new Set();
+  for (const match of body.match(PR_REFS_PATTERN) ?? []) {
+    for (const id of match.match(BEAD_ID_PATTERN) ?? []) beadIds.add(id);
+  }
+  if (beadIds.size === 0) return { ok: true, closed: [], skipped: [], errors: [] };
+
+  const closed = [];
+  const skipped = [];
+  const errors = [];
+  const reason = mergeCommitSha
+    ? `Merged via PR #${prNumber} (${mergeCommitSha.slice(0, 12)})`
+    : `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; }
+    try {
+      const result = spawnSync('bd', ['close', id, '--reason', reason], { cwd, encoding: 'utf8', timeout: 5000 });
+      if (result.status === 0) closed.push(id);
+      else errors.push({ id, reason: 'bd-close-failed', detail: (result.stderr || '').slice(0, 200) });
+    } catch (err) {
+      errors.push({ id, reason: 'bd-close-threw', detail: err?.message });
+    }
+  }
+
+  return { ok: true, closed, skipped, errors };
+}
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+function collectRecentObservations(rootDir, cutoff) {
+  const dir = join(rootDir, '.cx', 'observations');
+  if (!existsSync(dir)) return [];
+  const out = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (entry.isDirectory()) {
+      const subdir = join(dir, entry.name);
+      for (const file of safeReaddir(subdir)) {
+        const obs = readJsonSafe(join(subdir, file));
+        if (!obs) continue;
+        const ts = obs.timestamp || obs.ts;
+        if (!ts || new Date(ts) < cutoff) continue;
+        out.push({ ...obs, ts });
+      }
+    } else if (entry.name.endsWith('.json') || entry.name.endsWith('.jsonl')) {
+      const obs = readJsonSafe(join(dir, entry.name));
+      if (!obs) continue;
+      const ts = obs.timestamp || obs.ts;
+      if (!ts || new Date(ts) < cutoff) continue;
+      out.push({ ...obs, ts });
+    }
+  }
+  out.sort((a, b) => new Date(b.ts) - new Date(a.ts));
+  return out;
+}
+
+function collectRecentCommits(rootDir, cutoff) {
+  try {
+    const result = spawnSync('git', ['log', '--since', cutoff.toISOString(), '--pretty=format:%H|%s|%cI'], {
+      cwd: rootDir,
+      encoding: 'utf8',
+      timeout: 3000,
+    });
+    if (result.status !== 0) return [];
+    return result.stdout.split('\n').filter(Boolean).map((line) => {
+      const [sha, subject, committerDate] = line.split('|');
+      return { sha, subject, committerDate };
+    });
+  } catch {
+    return [];
+  }
+}
+
+function collectRecentlyClosedBeads(rootDir, cutoff) {
+  const beads = runBdListJson(rootDir, ['list', '--status', 'closed', '--json']);
+  return beads
+    .filter((b) => {
+      const ts = b.closed || b.updated || b.updatedAt;
+      return ts && new Date(ts) >= cutoff;
+    })
+    .sort((a, b) => new Date(b.closed || b.updated || b.updatedAt) - new Date(a.closed || a.updated || a.updatedAt));
+}
+
+function collectInProgressBeads(rootDir) {
+  return runBdListJson(rootDir, ['list', '--status', 'in_progress', '--json']);
+}
+
+function runBdListJson(rootDir, args) {
+  try {
+    const result = spawnSync('bd', args, { cwd: rootDir, encoding: 'utf8', timeout: 5000 });
+    if (result.status !== 0) return [];
+    const parsed = JSON.parse(result.stdout);
+    if (Array.isArray(parsed)) return parsed;
+    if (parsed && Array.isArray(parsed.issues)) return parsed.issues;
+    return [];
+  } catch {
+    return [];
+  }
+}
+
+function readBeadStatus(cwd, id) {
+  try {
+    const result = spawnSync('bd', ['show', id, '--json'], { cwd, encoding: 'utf8', timeout: 3000 });
+    if (result.status !== 0) return null;
+    const parsed = JSON.parse(result.stdout);
+    return parsed?.status || null;
+  } catch {
+    return null;
+  }
+}
+
+function readPrBody(prNumber, cwd) {
+  try {
+    const result = spawnSync('gh', ['pr', 'view', String(prNumber), '--json', 'body'], {
+      cwd,
+      encoding: 'utf8',
+      timeout: 10000,
+    });
+    if (result.status !== 0) return null;
+    const parsed = JSON.parse(result.stdout);
+    return parsed?.body || null;
+  } catch {
+    return null;
+  }
+}
+
+function safeReaddir(dir) {
+  try { return readdirSync(dir); }
+  catch { return []; }
+}
+
+function readJsonSafe(path) {
+  try { return JSON.parse(readFileSync(path, 'utf8')); }
+  catch { return null; }
+}
+
+function formatActiveWork(openBeads) {
+  if (openBeads.length === 0) return '_None in progress._';
+  return openBeads
+    .slice(0, CONTEXT_MAX_ITEMS_PER_SECTION)
+    .map((b) => `- **${b.id}** · ${b.title}`)
+    .join('\n');
+}
+
+function formatRecentDecisions(observations, commits, closedBeads) {
+  const items = [];
+  for (const bead of closedBeads.slice(0, CONTEXT_MAX_ITEMS_PER_SECTION)) {
+    items.push(`- closed **${bead.id}** · ${bead.title}`);
+  }
+  for (const commit of commits.slice(0, CONTEXT_MAX_ITEMS_PER_SECTION)) {
+    items.push(`- commit \`${commit.sha.slice(0, 10)}\` — ${commit.subject}`);
+  }
+  for (const obs of observations.filter((o) => o.category === 'decision').slice(0, CONTEXT_MAX_ITEMS_PER_SECTION)) {
+    items.push(`- decision — ${obs.summary}`);
+  }
+  if (items.length === 0) return '_No recent decisions captured._';
+  return items.slice(0, CONTEXT_MAX_ITEMS_PER_SECTION * 2).join('\n');
+}
+
+function formatArchitectureNotes(observations) {
+  const arch = observations
+    .filter((o) => o.category === 'architecture' || /architect|contract|boundary|invariant/i.test(o.summary || ''))
+    .slice(0, CONTEXT_MAX_ITEMS_PER_SECTION);
+  if (arch.length === 0) return '_No new architecture notes._';
+  return arch.map((o) => `- ${o.summary}`).join('\n');
+}
+
+function rewriteManagedSections(content, sections) {
+  let out = content;
+  for (const [key, header] of Object.entries(SECTION_HEADERS)) {
+    if (!(key in sections)) continue;
+    const body = sections[key];
+    out = replaceSection(out, header, body);
+  }
+  return out;
+}
+
+function replaceSection(content, header, body) {
+  const lines = content.split('\n');
+  const startIdx = lines.findIndex((l) => l.trim() === header);
+  if (startIdx === -1) return content;
+
+  let endIdx = lines.length;
+  for (let i = startIdx + 1; i < lines.length; i++) {
+    if (lines[i].startsWith('## ') && lines[i].trim() !== header) {
+      endIdx = i;
+      break;
+    }
+  }
+  const before = lines.slice(0, startIdx + 1);
+  const after = lines.slice(endIdx);
+  return [...before, '', body, '', ...after].join('\n');
+}

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/lib/worker/trace.mjs

@@ -26,15 +26,29 @@
  *   memory.written         — durable memory record persisted
  */
 
-import { existsSync, mkdirSync, appendFileSync } from 'node:fs';
+import { existsSync, mkdirSync } from 'node:fs';
 import { randomBytes } from 'node:crypto';
 import path from 'node:path';
 
 import { createTelemetryClient } from '../telemetry/client.mjs';
 import { ensureCxDir } from '../project-init-shared.mjs';
+import { appendWithRotationSync } from '../logging/rotate.mjs';
 
 const TRACE_SUBDIR = '.cx/traces';
 
+// GitHub rejects single files > 100 MB. Keep every trace shard strictly
+// under 100 MB so an accidental commit + push doesn't brick the repo. Cap
+// is configurable via CONSTRUCT_TRACE_MAX_MB; default 100. Override of 0
+// disables rotation entirely (not recommended).
+
+function traceMaxBytes(env = process.env) {
+  const raw = env.CONSTRUCT_TRACE_MAX_MB;
+  if (raw === undefined) return 100 * 1024 * 1024;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || parsed <= 0) return 0;
+  return Math.floor(parsed * 1024 * 1024);
+}
+
 export const TRACE_EVENT_TYPES = [
   'daemon.started',
   'daemon.heartbeat',
@@ -168,7 +182,10 @@ export function emitTraceEvent({
     metadata,
     createdAt: new Date().toISOString(),
   };
-  appendFileSync(path.join(dir, `${todayShard()}.jsonl`), `${JSON.stringify(event)}\n`, 'utf8');
+  const shardPath = path.join(dir, `${todayShard()}.jsonl`);
+  appendWithRotationSync(shardPath, `${JSON.stringify(event)}\n`, {
+    maxBytes: traceMaxBytes(env),
+  });
 
   // Fire-and-forget export to the configured remote adapter. Silent no-op when not configured.
   exportToRemote(event, env, rootDir);