@geraldmaron/construct 1.0.4 → 1.0.5

package/lib/profiles/loader.mjs

@@ -0,0 +1,123 @@
+/**
+ * lib/profiles/loader.mjs — Curated and custom org-type profile loader.
+ *
+ * Reads JSON profiles from `<repo>/profiles/<id>.json` for the curated set
+ * (rnd, marketing, game-studio, internal-tools), and from `<cwd>/.cx/profile.json`
+ * for user-defined profiles when `custom: true`.
+ *
+ * Resolution order for the active profile:
+ *   1. `construct.config.json` -> `profile`
+ *   2. `<cwd>/.cx/profile.json` -> `id` (custom)
+ *   3. Default: 'rnd'
+ *
+ * All errors fall back to 'rnd' so a malformed profile never breaks the CLI.
+ * Validation surfaces in `npm run lint:profiles` and in B3's pre-push gate.
+ */
+
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const MODULE_DIR = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = resolve(MODULE_DIR, '..', '..');
+const PROFILES_DIR = join(REPO_ROOT, 'profiles');
+
+export const DEFAULT_PROFILE_ID = 'rnd';
+
+/**
+ * Read a profile by id from the curated catalog. Returns null if not found.
+ */
+export function loadProfile(id) {
+  if (!id || typeof id !== 'string') return null;
+  const path = join(PROFILES_DIR, `${id}.json`);
+  if (!existsSync(path)) return null;
+  try {
+    const raw = JSON.parse(readFileSync(path, 'utf8'));
+    return raw;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * List every curated profile id by scanning the profiles directory.
+ */
+export function listProfiles() {
+  if (!existsSync(PROFILES_DIR)) return [];
+  return readdirSync(PROFILES_DIR)
+    .filter((f) => f.endsWith('.json'))
+    .map((f) => f.replace(/\.json$/, ''))
+    .sort();
+}
+
+/**
+ * Load a user-defined profile from `<cwd>/.cx/profile.json`. Returns null if
+ * the file is missing, malformed, or does not have `custom: true`.
+ */
+export function loadCustomProfile(cwd) {
+  if (!cwd) return null;
+  const path = join(cwd, '.cx', 'profile.json');
+  if (!existsSync(path)) return null;
+  try {
+    const raw = JSON.parse(readFileSync(path, 'utf8'));
+    if (raw && raw.custom === true) return raw;
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Resolve the active profile for a project. Always returns a profile object.
+ *
+ * Precedence (highest first):
+ *   1. Explicit `configProfileId` argument
+ *   2. `<cwd>/.cx/profile.json` with `custom: true`
+ *   3. `profile` field in `<cwd>/construct.config.json`
+ *   4. Default `rnd`
+ *
+ * Falls back to a minimal RND object on any miss so the CLI never breaks.
+ *
+ * @param {string} cwd - project root
+ * @param {string} [configProfileId] - explicit override, bypasses file lookups
+ */
+export function resolveActiveProfile(cwd, configProfileId = null) {
+  if (configProfileId) {
+    const p = loadProfile(configProfileId);
+    if (p) return p;
+  }
+  const custom = loadCustomProfile(cwd);
+  if (custom) return custom;
+  const fromConfig = readProfileFromProjectConfig(cwd);
+  if (fromConfig) {
+    const p = loadProfile(fromConfig);
+    if (p) return p;
+  }
+  return loadProfile(DEFAULT_PROFILE_ID) ?? minimalRndFallback();
+}
+
+function readProfileFromProjectConfig(cwd) {
+  if (!cwd) return null;
+  const p = join(cwd, 'construct.config.json');
+  if (!existsSync(p)) return null;
+  try {
+    const raw = JSON.parse(readFileSync(p, 'utf8'));
+    return typeof raw?.profile === 'string' ? raw.profile : null;
+  } catch {
+    return null;
+  }
+}
+
+// Last-resort fallback if the curated rnd profile file is missing or
+// unreadable. Lets callers always rely on a non-null shape.
+function minimalRndFallback() {
+  return {
+    id: 'rnd',
+    displayName: 'Software R&D',
+    roles: [],
+    intake: { types: [], stages: [] },
+    docTemplates: [],
+    hooks: { sessionReflect: 'on', sessionOptimize: 'on' },
+    rebrand: { intakeQueueLabel: 'R&D intake queue', signalNoun: 'signal' },
+  };
+}

package/lib/profiles/validate-custom.mjs

@@ -0,0 +1,114 @@
+/**
+ * lib/profiles/validate-custom.mjs — Schema validator for user-defined profiles.
+ *
+ * Custom profiles live at `<project>/.cx/profile.json` with `custom: true`.
+ * They are validated on `construct sync` and via the pre-push gate. Rejected
+ * profiles never get loaded; resolveActiveProfile falls back to the default
+ * so a malformed escape-hatch file never breaks a project.
+ *
+ * Hard limits the validator enforces (kept in sync with schemas/profile.schema.json
+ * and scripts/lint-profiles.mjs):
+ *   - max 12 stages
+ *   - max 24 intake types
+ *   - max 80 roles per profile
+ *   - max 12 departments per profile
+ *   - max 20 roles per department
+ *   - classificationTable path must stay inside .cx/ (no repo escapes)
+ *
+ * Rationale for each cap lives in docs/concepts/persona-research.md.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+const MAX_STAGES = 12;
+const MAX_INTAKE_TYPES = 24;
+const MAX_ROLES = 80;
+const MAX_DEPARTMENTS = 12;
+const MAX_ROLES_PER_DEPARTMENT = 20;
+
+/**
+ * @returns {string[]} array of error strings; empty means valid.
+ */
+export function validateCustomProfile(profile, { cwd } = {}) {
+  const errors = [];
+  if (!profile || typeof profile !== 'object') return ['profile is not an object'];
+  if (profile.custom !== true) errors.push('custom profiles must set custom: true');
+
+  if (!profile.id || !/^[a-z][a-z0-9-]{1,30}$/.test(profile.id)) {
+    errors.push('id must match ^[a-z][a-z0-9-]{1,30}$');
+  }
+  if (!profile.displayName || typeof profile.displayName !== 'string') {
+    errors.push('displayName is required');
+  }
+  if (!Array.isArray(profile.roles) || profile.roles.length === 0) {
+    errors.push('roles must be a non-empty array');
+  } else if (profile.roles.length > MAX_ROLES) {
+    errors.push(`roles exceeds max of ${MAX_ROLES}`);
+  }
+  if (!profile.intake || typeof profile.intake !== 'object') {
+    errors.push('intake is required');
+  } else {
+    if (!Array.isArray(profile.intake.types) || profile.intake.types.length === 0) {
+      errors.push('intake.types must be a non-empty array');
+    } else if (profile.intake.types.length > MAX_INTAKE_TYPES) {
+      errors.push(`intake.types exceeds max of ${MAX_INTAKE_TYPES}`);
+    }
+    if (!Array.isArray(profile.intake.stages) || profile.intake.stages.length === 0) {
+      errors.push('intake.stages must be a non-empty array');
+    } else if (profile.intake.stages.length > MAX_STAGES) {
+      errors.push(`intake.stages exceeds max of ${MAX_STAGES}`);
+    }
+    if (typeof profile.intake.classificationTable === 'string') {
+      const t = profile.intake.classificationTable;
+      if (path.isAbsolute(t)) {
+        errors.push('intake.classificationTable must be a relative path');
+      } else if (cwd && !t.startsWith('.cx/')) {
+        errors.push('intake.classificationTable must live under .cx/ for custom profiles');
+      }
+    }
+  }
+  if (profile.departments !== undefined) {
+    if (!Array.isArray(profile.departments)) {
+      errors.push('departments must be an array');
+    } else {
+      if (profile.departments.length > MAX_DEPARTMENTS) {
+        errors.push(`departments exceeds max of ${MAX_DEPARTMENTS}`);
+      }
+      for (const [i, dept] of profile.departments.entries()) {
+        if (!dept || typeof dept !== 'object') {
+          errors.push(`departments[${i}] must be an object`);
+          continue;
+        }
+        if (!dept.id || !/^[a-z][a-z0-9-]{1,40}$/.test(dept.id)) {
+          errors.push(`departments[${i}].id is missing or malformed`);
+        }
+        if (!dept.charter || dept.charter.length < 20) {
+          errors.push(`departments[${i}].charter must be at least 20 chars (mission statement, not a label)`);
+        }
+        if (!Array.isArray(dept.roles) || dept.roles.length === 0) {
+          errors.push(`departments[${i}].roles must be a non-empty array`);
+        } else if (dept.roles.length > MAX_ROLES_PER_DEPARTMENT) {
+          errors.push(`departments[${i}].roles exceeds max of ${MAX_ROLES_PER_DEPARTMENT}`);
+        }
+      }
+    }
+  }
+  return errors;
+}
+
+/**
+ * Read and validate `<cwd>/.cx/profile.json`. Returns:
+ *   { status: 'absent' }                 if the file does not exist
+ *   { status: 'invalid', errors: [...] } if validation failed
+ *   { status: 'ok', profile }            if the file is a valid custom profile
+ */
+export function validateCustomProfileFile(cwd) {
+  const p = path.join(cwd, '.cx', 'profile.json');
+  if (!fs.existsSync(p)) return { status: 'absent' };
+  let raw;
+  try { raw = JSON.parse(fs.readFileSync(p, 'utf8')); }
+  catch (err) { return { status: 'invalid', errors: [`malformed JSON: ${err.message}`] }; }
+  const errors = validateCustomProfile(raw, { cwd });
+  if (errors.length > 0) return { status: 'invalid', errors };
+  return { status: 'ok', profile: raw };
+}

package/lib/reflect/extractor.mjs

@@ -0,0 +1,193 @@
+/**
+ * lib/reflect/extractor.mjs — Deterministic transcript → observation extractor.
+ *
+ * Pure-function pass over a Claude Code transcript JSONL. Produces a compact
+ * structured summary suitable for `addObservation()` at session end. No LLM
+ * call — the transcript itself is the source of truth.
+ *
+ * Caller responsibility: read the transcript file and pass parsed lines.
+ * Output is capped at MAX_BYTES to honor the A1 hook's per-session budget.
+ */
+
+// Hard cap on the summary content so a runaway session can't blow up the
+// observation store. 5 KB matches the budget set in the A1 plan.
+const MAX_BYTES = 5 * 1024;
+const MAX_TAGS = 10;
+const MAX_TOOL_TYPES = 8;
+const MAX_FILES = 12;
+
+/**
+ * Extract a session-summary observation from a parsed transcript.
+ *
+ * @param {object} args
+ * @param {object[]} args.entries — parsed transcript JSONL lines (objects)
+ * @param {string} args.cwd — session working directory
+ * @param {string} [args.sessionId] — session identifier
+ * @param {number} [args.durationMs] — wall-clock session duration
+ * @returns {object|null} observation payload, or null if transcript is unusable
+ */
+export function extractSessionObservation({ entries, cwd, sessionId, durationMs }) {
+  if (!Array.isArray(entries) || entries.length === 0) return null;
+
+  const stats = collectStats(entries);
+  if (stats.assistantTurns === 0 && stats.userTurns === 0) return null;
+
+  const finalAssistant = stats.lastAssistantText;
+  const headline = deriveHeadline(finalAssistant, stats);
+
+  const lines = [];
+  lines.push(`Session: ${stats.userTurns} user turns, ${stats.assistantTurns} assistant turns`);
+  if (stats.toolCallCount > 0) {
+    const tools = Array.from(stats.toolTypes.entries())
+      .sort((a, b) => b[1] - a[1])
+      .slice(0, MAX_TOOL_TYPES)
+      .map(([name, n]) => `${name}×${n}`)
+      .join(', ');
+    lines.push(`Tools: ${stats.toolCallCount} calls (${tools})`);
+  }
+  if (stats.filesTouched.size > 0) {
+    const files = Array.from(stats.filesTouched).slice(0, MAX_FILES);
+    lines.push(`Files touched: ${files.join(', ')}${stats.filesTouched.size > MAX_FILES ? ', …' : ''}`);
+  }
+  if (durationMs && Number.isFinite(durationMs)) {
+    lines.push(`Duration: ${Math.round(durationMs / 1000)}s`);
+  }
+  if (finalAssistant) {
+    lines.push('', 'Final response excerpt:', clamp(finalAssistant, 800));
+  }
+
+  const content = clamp(lines.join('\n'), MAX_BYTES);
+
+  return {
+    role: stats.lastAgent || 'construct',
+    category: 'session-summary',
+    summary: headline,
+    content,
+    tags: buildTags(stats),
+    confidence: 0.7,
+    source: 'auto-reflect',
+    extras: {
+      sessionId: sessionId || null,
+      cwd,
+      durationMs: durationMs ?? null,
+      userTurns: stats.userTurns,
+      assistantTurns: stats.assistantTurns,
+      toolCallCount: stats.toolCallCount,
+      filesTouched: Array.from(stats.filesTouched).slice(0, MAX_FILES),
+    },
+  };
+}
+
+// Walk the transcript once and gather everything we need in one pass. Keeps
+// the hook well under its latency budget even on long sessions.
+
+function collectStats(entries) {
+  const toolTypes = new Map();
+  const filesTouched = new Set();
+  let assistantTurns = 0;
+  let userTurns = 0;
+  let toolCallCount = 0;
+  let lastAssistantText = '';
+  let lastAgent = null;
+
+  for (const entry of entries) {
+    if (!entry || typeof entry !== 'object') continue;
+    const type = entry.type;
+
+    if (type === 'user') {
+      userTurns += 1;
+      continue;
+    }
+
+    if (type === 'assistant') {
+      assistantTurns += 1;
+      const text = extractAssistantText(entry);
+      if (text) lastAssistantText = text;
+      const calls = extractToolCalls(entry);
+      for (const call of calls) {
+        toolCallCount += 1;
+        toolTypes.set(call.name, (toolTypes.get(call.name) || 0) + 1);
+        for (const f of call.files) filesTouched.add(f);
+      }
+      const agent = extractAgentName(entry);
+      if (agent) lastAgent = agent;
+    }
+  }
+
+  return { assistantTurns, userTurns, toolCallCount, toolTypes, filesTouched, lastAssistantText, lastAgent };
+}
+
+function extractAssistantText(entry) {
+  const message = entry.message ?? entry;
+  const content = message?.content;
+  if (typeof content === 'string') return content.trim();
+  if (Array.isArray(content)) {
+    const text = content
+      .filter((p) => p?.type === 'text' && typeof p.text === 'string')
+      .map((p) => p.text)
+      .join('\n')
+      .trim();
+    return text;
+  }
+  return '';
+}
+
+function extractToolCalls(entry) {
+  const message = entry.message ?? entry;
+  const content = message?.content;
+  if (!Array.isArray(content)) return [];
+  const calls = [];
+  for (const part of content) {
+    if (part?.type !== 'tool_use') continue;
+    const name = part.name || 'unknown';
+    const files = [];
+    const input = part.input || {};
+    if (typeof input.file_path === 'string') files.push(shortenPath(input.file_path));
+    if (typeof input.path === 'string') files.push(shortenPath(input.path));
+    calls.push({ name, files });
+  }
+  return calls;
+}
+
+function extractAgentName(entry) {
+  // Claude Code may stamp the agent name on subagent transcripts. Fall through
+  // to null if not present — caller defaults to 'construct'.
+  return entry?.agent || entry?.subagent_type || entry?.message?.agent || null;
+}
+
+function deriveHeadline(finalText, stats) {
+  // First non-empty line of the final assistant turn is usually a good lead.
+  // Fall back to a structural summary when nothing useful is available.
+  if (finalText) {
+    const firstLine = finalText.split('\n').map((l) => l.trim()).find((l) => l.length > 0);
+    if (firstLine) {
+      const clean = firstLine.replace(/^[#*\->]\s*/, '').replace(/[`*_]/g, '');
+      return `[session] ${clamp(clean, 200)}`;
+    }
+  }
+  return `[session] ${stats.assistantTurns} turn${stats.assistantTurns === 1 ? '' : 's'}, ${stats.toolCallCount} tool call${stats.toolCallCount === 1 ? '' : 's'}`;
+}
+
+function buildTags(stats) {
+  const tags = ['auto-reflect', 'session-summary'];
+  // Surface the most-used tool family so search can filter on "Bash-heavy
+  // session", etc. without parsing content.
+  const top = Array.from(stats.toolTypes.entries()).sort((a, b) => b[1] - a[1]).slice(0, 3);
+  for (const [name] of top) tags.push(`tool:${name.toLowerCase()}`);
+  if (stats.filesTouched.size > 0) tags.push('edits');
+  return tags.slice(0, MAX_TAGS);
+}
+
+function shortenPath(p) {
+  if (typeof p !== 'string') return '';
+  // Strip a repo-root prefix when present so observations stay portable.
+  const cwd = process.cwd();
+  if (p.startsWith(cwd + '/')) return p.slice(cwd.length + 1);
+  return p;
+}
+
+function clamp(str, max) {
+  if (!str) return '';
+  if (str.length <= max) return str;
+  return str.slice(0, max - 1) + '…';
+}

package/lib/reflect.mjs

@@ -5,11 +5,13 @@
  * knowledge base with actionable insights for continuous self-improvement.
  */
 
-import { existsSync, mkdirSync, writeFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { existsSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { join, resolve, basename } from 'node:path';
+import { execSync } from 'node:child_process';
 import { addObservation } from './observation-store.mjs';
 import { loadConstructEnv } from './env-config.mjs';
 import { KNOWLEDGE_ROOT, KNOWLEDGE_SUBDIRS, inferKnowledgeTarget } from './knowledge/layout.mjs';
+import { extractSessionObservation } from './reflect/extractor.mjs';
 
 const HOME = process.env.HOME || process.env.USERPROFILE;
 const USER_ENV_PATH = join(HOME, '.construct', 'config.env');
@@ -125,6 +127,91 @@ export async function runReflectCli(args) {
   console.log(`  Use 'construct ingest --target=${target} <file>' to manually add similar feedback in the future`);
 }
 
+/**
+ * Auto-reflect from a Claude Code Stop hook payload.
+ *
+ * Reads the transcript JSONL, extracts a deterministic session summary, and
+ * persists it via the standard observation store. Contract: exit fast, fail
+ * silent, never throw — every error path returns null so the hook always
+ * exits 0.
+ *
+ * Returns the recorded observation id on success, null on no-op.
+ *
+ * @param {object} args
+ * @param {string} args.transcriptPath — path to the Stop hook's transcript_path
+ * @param {string} args.cwd — session cwd (the project root)
+ * @param {string} [args.sessionId]
+ * @param {number} [args.durationMs]
+ * @returns {Promise<string|null>}
+ */
+export async function runReflectAuto({ transcriptPath, cwd, sessionId, durationMs }) {
+  if (!transcriptPath || !cwd) return null;
+  if (!existsSync(transcriptPath)) return null;
+
+  const entries = parseTranscript(transcriptPath);
+  if (entries.length === 0) return null;
+
+  const observation = extractSessionObservation({ entries, cwd, sessionId, durationMs });
+  if (!observation) return null;
+
+  // Skip trivial sessions: no tool calls AND no substantive final text. Avoids
+  // polluting the observation store with one-line acknowledgements.
+  const trivial =
+    observation.extras?.toolCallCount === 0 &&
+    (observation.content?.length || 0) < 120;
+  if (trivial) return null;
+
+  const project = safeProject(cwd);
+  const gitSha = safeGitSha(cwd);
+
+  // Session-id stays in tags so the index can filter by it without parsing.
+  // Structured metadata goes into the new extras field, not into content.
+  const sessionTag = sessionId ? `session:${sessionId.slice(0, 24)}` : null;
+  const tags = [...observation.tags];
+  if (sessionTag) tags.push(sessionTag);
+
+  const result = await addObservation(cwd, {
+    role: observation.role,
+    category: observation.category,
+    summary: observation.summary,
+    content: observation.content,
+    tags,
+    project,
+    gitSha,
+    confidence: observation.confidence,
+    source: observation.source,
+    extras: observation.extras ?? null,
+  });
+
+  return result?.id ?? null;
+}
+
+function safeProject(cwd) {
+  try { return basename(cwd) || null; } catch { return null; }
+}
+
+function safeGitSha(cwd) {
+  try {
+    return execSync('git rev-parse HEAD', { cwd, stdio: ['ignore', 'pipe', 'ignore'], timeout: 200 })
+      .toString().trim().slice(0, 40) || null;
+  } catch { return null; }
+}
+
+// Transcripts are JSONL; one JSON object per line. Be permissive — a single
+// malformed line shouldn't lose the rest of the session.
+
+function parseTranscript(path) {
+  let raw = '';
+  try { raw = readFileSync(path, 'utf8'); } catch { return []; }
+  const out = [];
+  for (const line of raw.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try { out.push(JSON.parse(trimmed)); } catch { /* skip malformed */ }
+  }
+  return out;
+}
+
 /**
  * CLI entry point for direct execution.
  */

package/lib/sandbox.mjs

@@ -0,0 +1,102 @@
+/**
+ * lib/sandbox.mjs — Lightweight isolated environment for QA validation.
+ *
+ * Spins up a fresh tmpdir with a minimal `.cx/` so a specialist (or operator)
+ * can run end-to-end checks against a candidate change without touching the
+ * working repo. Designed to be the cheapest possible alternative to a full
+ * Docker container: when Docker is unavailable, an isolated tmpdir is enough
+ * for almost every validation Construct needs.
+ *
+ * Layout created:
+ *   <sandbox>/.cx/
+ *     context.md             stub
+ *     observations/          empty
+ *     intake/pending/        empty
+ *   <sandbox>/.git/          empty repo init, so git-aware tools work
+ *
+ * Tear-down is opt-in via `construct sandbox prune` or by hand. Each sandbox
+ * lives under `~/.cx/sandboxes/<id>/` so they survive across CLI sessions.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+const ROOT = path.join(os.homedir(), '.cx', 'sandboxes');
+
+function ensureRoot() {
+  fs.mkdirSync(ROOT, { recursive: true });
+}
+
+function newSandboxId() {
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+  const rand = Math.random().toString(36).slice(2, 8);
+  return `${stamp}-${rand}`;
+}
+
+/**
+ * Create a new sandbox. Returns its absolute path.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.profile] - profile id to write into construct.config.json
+ * @param {string} [opts.seedContext] - text to drop into .cx/context.md
+ * @returns {{ id: string, path: string }}
+ */
+export function createSandbox({ profile = null, seedContext = null } = {}) {
+  ensureRoot();
+  const id = newSandboxId();
+  const root = path.join(ROOT, id);
+  fs.mkdirSync(root, { recursive: true });
+  fs.mkdirSync(path.join(root, '.cx', 'observations'), { recursive: true });
+  fs.mkdirSync(path.join(root, '.cx', 'intake', 'pending'), { recursive: true });
+
+  const ctx = seedContext || `# Sandbox ${id}\n\nIsolated environment for QA validation. Created ${new Date().toISOString()}.\n`;
+  fs.writeFileSync(path.join(root, '.cx', 'context.md'), ctx);
+
+  const cfg = { version: 1, alias: 'Construct', deployment: { mode: 'solo' } };
+  if (profile) cfg.profile = profile;
+  fs.writeFileSync(path.join(root, 'construct.config.json'), JSON.stringify(cfg, null, 2) + '\n');
+
+  spawnSync('git', ['init', '--quiet'], { cwd: root, stdio: 'ignore' });
+
+  return { id, path: root };
+}
+
+/**
+ * List existing sandboxes, newest first.
+ */
+export function listSandboxes() {
+  if (!fs.existsSync(ROOT)) return [];
+  const entries = fs.readdirSync(ROOT, { withFileTypes: true })
+    .filter((d) => d.isDirectory())
+    .map((d) => {
+      const full = path.join(ROOT, d.name);
+      const stat = fs.statSync(full);
+      return { id: d.name, path: full, createdAt: stat.birthtime.toISOString() };
+    });
+  return entries.sort((a, b) => b.createdAt.localeCompare(a.createdAt));
+}
+
+/**
+ * Delete a sandbox by id. Returns true if removed, false if not found.
+ */
+export function deleteSandbox(id) {
+  const full = path.join(ROOT, id);
+  if (!fs.existsSync(full)) return false;
+  fs.rmSync(full, { recursive: true, force: true });
+  return true;
+}
+
+/**
+ * Prune sandboxes older than N days. Returns the count removed.
+ */
+export function pruneSandboxes({ olderThanDays = 7 } = {}) {
+  const cutoff = Date.now() - olderThanDays * 24 * 60 * 60 * 1000;
+  let removed = 0;
+  for (const s of listSandboxes()) {
+    if (Date.parse(s.createdAt) < cutoff) {
+      if (deleteSandbox(s.id)) removed++;
+    }
+  }
+  return removed;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geraldmaron/construct",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "type": "module",
   "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",
   "bin": {
@@ -42,12 +42,17 @@
   "scripts": {
     "mcp": "node lib/mcp/server.mjs",
     "test": "node scripts/run-tests.mjs",
+    "test:functional": "node --test --test-timeout=30000 tests/functional/*.functional.test.mjs",
+    "test:unit": "node scripts/run-tests.mjs --exclude=tests/functional",
     "docs:init": "node lib/init-docs.mjs --yes",
     "docs:update": "node ./bin/construct docs:update",
     "docs:site": "node ./bin/construct docs:site",
     "docs:dev": "npm --prefix apps/docs run dev",
     "docs:build": "npm --prefix apps/docs run build",
     "lint:comments": "node ./bin/construct lint:comments",
+    "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",
     "eval:routing": "node scripts/eval/score-intent-classifier.mjs",
     "release:check": "node ./bin/construct doctor && npm test && node ./bin/construct docs:update --check && node ./bin/construct dashboard:sync --check && node ./bin/construct lint:comments && node scripts/lint-commits-pr.mjs",