@geraldmaron/construct 1.0.3 → 1.0.5

package/lib/telemetry/client.mjs

@@ -0,0 +1,185 @@
+/**
+ * lib/telemetry/client.mjs — shared local-first telemetry adapter.
+ *
+ * Local JSONL trace capture is the default. Remote export is opt-in through
+ * CONSTRUCT_TRACE_BACKEND and never throws into callers.
+ */
+import { existsSync, mkdirSync, appendFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+import { createIngestClient } from './ingest.mjs';
+
+const DEFAULT_MAX_BATCH = 50;
+
+export const TRACE_BACKENDS = new Set(['local', 'langfuse', 'http', 'otel', 'none']);
+
+function cleanUrl(value = '') {
+  return String(value || '').replace(/\/$/, '');
+}
+
+function inferRemoteBackend(env) {
+  const url = cleanUrl(env.CONSTRUCT_TELEMETRY_URL);
+  const hasKeys = Boolean(env.CONSTRUCT_TELEMETRY_PUBLIC_KEY && env.CONSTRUCT_TELEMETRY_SECRET_KEY);
+  if (!url) return 'local';
+  return hasKeys ? 'langfuse' : 'http';
+}
+
+export function resolveTraceBackend(env = process.env) {
+  const raw = String(env.CONSTRUCT_TRACE_BACKEND || '').trim().toLowerCase();
+  if (!raw) return inferRemoteBackend(env);
+  if (raw === 'remote' || raw === 'telemetry') return inferRemoteBackend(env);
+  if (raw === 'off') return 'none';
+  return TRACE_BACKENDS.has(raw) ? raw : 'local';
+}
+
+export function telemetryProviderLabel(env = process.env) {
+  return env.CONSTRUCT_TELEMETRY_PROVIDER || resolveTraceBackend(env);
+}
+
+function resolveProjectRoot({ rootDir, env = process.env } = {}) {
+  return rootDir || env.CX_TOOLKIT_DIR || env.PWD || process.cwd();
+}
+
+function localTraceEnabled(env = process.env) {
+  return env.CONSTRUCT_TRACE_LOCAL_ENABLED !== '0';
+}
+
+function traceShard() {
+  return new Date().toISOString().slice(0, 10);
+}
+
+function appendLocalTelemetry(type, body, { rootDir, env = process.env, onError = () => {} } = {}) {
+  if (!localTraceEnabled(env)) return;
+  const projectRoot = resolveProjectRoot({ rootDir, env });
+  const dir = join(projectRoot, '.cx', 'traces');
+  try {
+    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    appendFileSync(join(dir, `${traceShard()}.jsonl`), `${JSON.stringify({
+      traceId: body?.traceId || body?.id || randomUUID(),
+      spanId: body?.id || randomUUID(),
+      eventType: `telemetry.${type}`,
+      telemetryType: type,
+      project: body?.metadata?.project || body?.project || null,
+      role: body?.metadata?.agent || body?.metadata?.agentName || body?.name || null,
+      metadata: body?.metadata || {},
+      input: body?.input,
+      output: body?.output,
+      createdAt: body?.timestamp || body?.startTime || new Date().toISOString(),
+    })}\n`, 'utf8');
+  } catch (err) {
+    onError(err);
+  }
+}
+
+function buildOtlpPayload(batch) {
+  return {
+    resourceSpans: [{
+      resource: {
+        attributes: [
+          { key: 'service.name', value: { stringValue: 'construct' } },
+        ],
+      },
+      scopeSpans: [{
+        scope: { name: 'construct.telemetry' },
+        spans: batch.map((item) => {
+          const body = item.body || {};
+          const startedAt = Date.parse(body.startTime || body.timestamp || item.timestamp || new Date().toISOString());
+          const endedAt = Date.parse(body.endTime || body.startTime || body.timestamp || item.timestamp || new Date().toISOString());
+          return {
+            traceId: String(body.traceId || body.id || item.id).replace(/[^a-fA-F0-9]/g, '').padEnd(32, '0').slice(0, 32),
+            spanId: String(body.id || item.id).replace(/[^a-fA-F0-9]/g, '').padEnd(16, '0').slice(0, 16),
+            name: body.name || item.type,
+            kind: 1,
+            startTimeUnixNano: String(Math.max(0, startedAt) * 1_000_000),
+            endTimeUnixNano: String(Math.max(0, endedAt) * 1_000_000),
+            attributes: [
+              { key: 'construct.telemetry.type', value: { stringValue: item.type } },
+              ...(body.model ? [{ key: 'llm.model_name', value: { stringValue: String(body.model) } }] : []),
+            ],
+          };
+        }),
+      }],
+    }],
+  };
+}
+
+function createRemoteClient({ backend, env, fetchImpl, onError }) {
+  if (backend === 'local' || backend === 'none') return null;
+  if (backend === 'otel') {
+    const endpoint = cleanUrl(env.CONSTRUCT_OTEL_EXPORTER_OTLP_ENDPOINT);
+    return createIngestClient({
+      baseUrl: endpoint,
+      endpointPath: endpoint.endsWith('/v1/traces') ? '' : '/v1/traces',
+      authMode: 'none',
+      payloadBuilder: buildOtlpPayload,
+      fetchImpl,
+      onError,
+      maxBatch: DEFAULT_MAX_BATCH,
+    });
+  }
+  if (backend === 'http') {
+    return createIngestClient({
+      baseUrl: cleanUrl(env.CONSTRUCT_TELEMETRY_URL),
+      endpointPath: '/ingest',
+      authMode: 'none',
+      fetchImpl,
+      onError,
+      maxBatch: DEFAULT_MAX_BATCH,
+    });
+  }
+  return createIngestClient({
+    baseUrl: cleanUrl(env.CONSTRUCT_TELEMETRY_URL),
+    publicKey: env.CONSTRUCT_TELEMETRY_PUBLIC_KEY,
+    secretKey: env.CONSTRUCT_TELEMETRY_SECRET_KEY,
+    fetchImpl,
+    onError,
+    maxBatch: DEFAULT_MAX_BATCH,
+  });
+}
+
+export function createTelemetryClient({
+  env = process.env,
+  rootDir,
+  fetchImpl = globalThis.fetch,
+  onError = () => {},
+  localWrites = true,
+} = {}) {
+  const backend = resolveTraceBackend(env);
+  const remote = createRemoteClient({ backend, env, fetchImpl, onError });
+  const localAvailable = localWrites && localTraceEnabled(env);
+  const remoteAvailable = Boolean(remote?.available);
+
+  function emit(type, body) {
+    if (!body) return;
+    if (localWrites) appendLocalTelemetry(type, body, { rootDir, env, onError });
+    if (!remoteAvailable) return;
+    try {
+      remote[type]?.(body);
+    } catch (err) {
+      onError(err);
+    }
+  }
+
+  return {
+    backend,
+    provider: telemetryProviderLabel(env),
+    available: localAvailable || remoteAvailable,
+    localAvailable,
+    remoteAvailable,
+    remoteStatus: remoteAvailable ? 'configured' : backend === 'local' || backend === 'none' ? backend : 'unconfigured',
+    trace: (body) => emit('trace', body),
+    traceUpdate: (body) => emit('traceUpdate', body),
+    generation: (body) => emit('generation', body),
+    generationUpdate: (body) => emit('generationUpdate', body),
+    span: (body) => emit('span', body),
+    spanUpdate: (body) => emit('spanUpdate', body),
+    event: (body) => emit('event', body),
+    score: (body) => emit('score', body),
+    async flush() {
+      if (remote?.flush) await remote.flush();
+    },
+    queueSize: () => remote?.queueSize?.() ?? 0,
+  };
+}

package/lib/telemetry/ingest.mjs

@@ -35,17 +35,21 @@ export function createIngestClient({
   ).replace(/\/$/, ''),
   publicKey = process.env.CONSTRUCT_TELEMETRY_PUBLIC_KEY,
   secretKey = process.env.CONSTRUCT_TELEMETRY_SECRET_KEY,
+  endpointPath = '/api/public/ingestion',
+  authMode = 'basic',
+  payloadBuilder = (batch) => ({ batch }),
   flushIntervalMs = DEFAULT_FLUSH_INTERVAL_MS,
   maxBatch = DEFAULT_MAX_BATCH,
   onError = () => {},
   fetchImpl = globalThis.fetch,
 } = {}) {
-  const available = Boolean(publicKey && secretKey && fetchImpl);
+  const requiresBasicAuth = authMode === 'basic';
+  const available = Boolean(baseUrl && fetchImpl && (!requiresBasicAuth || (publicKey && secretKey)));
   const queue = [];
   let flushTimer = null;
   let inflight = Promise.resolve();
 
-  const authHeader = available
+  const authHeader = available && requiresBasicAuth
     ? `Basic ${Buffer.from(`${publicKey}:${secretKey}`).toString('base64')}`
     : '';
 
@@ -61,14 +65,17 @@ export function createIngestClient({
   async function flushBatch() {
     if (!available || queue.length === 0) return;
     const batch = queue.splice(0, maxBatch);
-    const payload = JSON.stringify({ batch });
+    const payload = JSON.stringify(payloadBuilder(batch));
     const prev = inflight;
     inflight = (async () => {
       try { await prev; } catch { /* ignore prior */ }
       try {
-        const res = await fetchImpl(`${baseUrl}/api/public/ingestion`, {
+        const res = await fetchImpl(`${baseUrl}${endpointPath}`, {
           method: 'POST',
-          headers: { Authorization: authHeader, 'Content-Type': 'application/json' },
+          headers: {
+            ...(authHeader ? { Authorization: authHeader } : {}),
+            'Content-Type': 'application/json',
+          },
           body: payload,
         });
         if (!res.ok && res.status !== 207) {
@@ -104,6 +111,7 @@ export function createIngestClient({
     span: (body) => push('span-create', body),
     spanUpdate: (body) => push('span-update', body),
     event: (body) => push('event-create', body),
+    score: (body) => push('score-create', body),
     async flush() {
       if (flushTimer) { clearTimeout(flushTimer); flushTimer = null; }
       while (queue.length > 0) await flushBatch();

package/lib/telemetry/team-rollup.mjs

@@ -3,22 +3,29 @@
  *
  * Groups agent traces by teamId (stamped by construct headhunt at overlay creation),
  * computes per-team success rates, latency, handoff counts, and common blockers.
- * Backend is selected via CONSTRUCT_TRACE_BACKEND env var (default: remote).
+ * Backend is selected via CONSTRUCT_TRACE_BACKEND env var (default: local).
  * Called by 'construct team review'.
  */
 
 import * as remoteBackend from './backends/remote.mjs';
+import * as localBackend from './backends/local.mjs';
 import * as noopBackend from './backends/noop.mjs';
+import { resolveTraceBackend } from './client.mjs';
 
 const BACKENDS = {
+  local: localBackend,
+  langfuse: remoteBackend,
+  http: remoteBackend,
+  otel: noopBackend,
   remote: remoteBackend,
+  none: noopBackend,
   noop: noopBackend,
 };
 
 const DEFAULT_WINDOW_MS = 7 * 24 * 60 * 60 * 1000; // 7 days
 
 function resolveBackend() {
-  const name = process.env.CONSTRUCT_TRACE_BACKEND ?? 'remote';
+  const name = resolveTraceBackend(process.env);
   const backend = BACKENDS[name];
   if (!backend) throw new Error(`Unknown trace backend: ${name}. Available: ${Object.keys(BACKENDS).join(', ')}`);
   return backend;

package/lib/worker/trace.mjs

@@ -7,16 +7,11 @@
  *
  *   1. `.cx/traces/<YYYY-MM-DD>.jsonl` — append-only local JSONL. Always on,
  *      no credentials required. Tail live, archive, or replay.
- *   2. Remote telemetry backend — fire-and-forget batched ingest when
- *      CONSTRUCT_TELEMETRY_PUBLIC_KEY + CONSTRUCT_TELEMETRY_SECRET_KEY are
- *      configured and CONSTRUCT_TRACE_BACKEND is `remote` (or unset).
- *      Each unique traceId triggers one trace-create plus an event-create
- *      per emitted event. Failures never throw — observability must not
+ *   2. Optional remote export — selected by CONSTRUCT_TRACE_BACKEND. Each
+ *      unique traceId triggers one trace-create plus an event-create per
+ *      emitted event. Failures never throw because observability must not
  *      break the caller.
  *
- *      Reads CONSTRUCT_TELEMETRY_PUBLIC_KEY / CONSTRUCT_TELEMETRY_SECRET_KEY /
- *      CONSTRUCT_TELEMETRY_URL from env.
- *
  * Event types in current use:
  *   intake.received        — daemon ingested a file
  *   intake.triaged         — classifyRdIntake produced a triage block
@@ -35,7 +30,7 @@ import { existsSync, mkdirSync, appendFileSync } from 'node:fs';
 import { randomBytes } from 'node:crypto';
 import path from 'node:path';
 
-import { createIngestClient } from '../telemetry/ingest.mjs';
+import { createTelemetryClient } from '../telemetry/client.mjs';
 
 const TRACE_SUBDIR = '.cx/traces';
 
@@ -73,23 +68,18 @@ export function newSpanId() {
   return `span-${randomBytes(6).toString('hex')}`;
 }
 
-// Reused per-process. The ingest client batches; recreating it would lose
-// the queue. `available` flips false when keys aren't set, which is the
-// graceful no-op path for solo-mode users without no telemetry backend configured.
+// Reused per-process. The adapter batches remote export; recreating it would
+// lose the queue. Local JSONL is already written by emitTraceEvent, so this
+// client disables its own local writer.
 let telemetryClient = null;
 const seenTraces = new Set();
 
-function getTelemetryClient(env = process.env) {
+function getTelemetryClient(env = process.env, rootDir) {
   if (telemetryClient !== null) return telemetryClient;
-  const backend = (env.CONSTRUCT_TRACE_BACKEND || 'remote').toLowerCase();
-  if (backend === 'none' || backend === 'off' || backend === 'local') {
-    telemetryClient = { available: false, trace: () => {}, event: () => {} };
-    return telemetryClient;
-  }
-  telemetryClient = createIngestClient({
-    baseUrl: (env.CONSTRUCT_TELEMETRY_URL ?? '').replace(/\/$/, ''),
-    publicKey: env.CONSTRUCT_TELEMETRY_PUBLIC_KEY,
-    secretKey: env.CONSTRUCT_TELEMETRY_SECRET_KEY,
+  telemetryClient = createTelemetryClient({
+    env,
+    rootDir,
+    localWrites: false,
   });
   return telemetryClient;
 }
@@ -103,9 +93,9 @@ export function _resetTelemetryClient() {
 }
 
 
-function exportToRemote(event, env) {
-  const client = getTelemetryClient(env);
-  if (!client.available) return;
+function exportToRemote(event, env, rootDir) {
+  const client = getTelemetryClient(env, rootDir);
+  if (!client.remoteAvailable) return;
 
   // First time we see a traceId, register the trace so subsequent events
   // attach to a known parent.
@@ -176,7 +166,7 @@ export function emitTraceEvent({
   };
   appendFileSync(path.join(dir, `${todayShard()}.jsonl`), `${JSON.stringify(event)}\n`, 'utf8');
 
-  // Fire-and-forget export to remote telemetry backend. Silent no-op when not configured.
-  exportToRemote(event, env);
+  // Fire-and-forget export to the configured remote adapter. Silent no-op when not configured.
+  exportToRemote(event, env, rootDir);
   return event;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geraldmaron/construct",
-  "version": "1.0.3",
+  "version": "1.0.5",
   "type": "module",
   "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",
   "bin": {
@@ -42,15 +42,22 @@
   "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",
+    "release:preflight": "node scripts/pre-release-check.mjs",
+    "release:preflight:no-auth": "node scripts/pre-release-check.mjs --skip-auth",
     "npm:publish": "npm run release:check && npm publish --access public",
     "postinstall": "node ./bin/construct-postinstall.mjs"
   },
@@ -61,6 +68,7 @@
     "postgres": "^3.4.9"
   },
   "overrides": {
-    "express-rate-limit": "8.5.1"
+    "express-rate-limit": "8.5.1",
+    "protobufjs": "^8.4.2"
   }
 }

package/personas/construct.md

@@ -1,24 +1,24 @@
 <!--
-personas/construct.md — Construct persona prompt.
+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-agents
 and emitted to every supported platform.
 -->
-You are Construct — the single AI interface for everything from a quick question to a full software lifecycle. The user talks only to you; internal routing and specialist dispatch are implementation detail.
+You are Construct. the single AI interface for everything from a quick question to a full software lifecycle. The user talks only to you; internal routing and specialist dispatch are implementation detail.
 
 ## Start of every session
 
-Before responding, run in parallel — do not narrate:
-1. `project_context` — state from `.cx/context.md`
-2. `memory_search` with the basename of CWD — prior session context and user preferences
+Before responding, run in parallel. do not narrate:
+1. `project_context`. state from `.cx/context.md`
+2. `memory_search` with the basename of CWD. prior session context and user preferences
 3. Read `AGENTS.md`, `plan.md`, and the relevant docs for the current task when present
-4. Check `.cx/handoffs/` for the most recent handoff — if another session was active, read it to understand what was in progress and what NOT to touch
+4. Check `.cx/handoffs/` for the most recent handoff. if another session was active, read it to understand what was in progress and what NOT to touch
 
 Apply results silently. If memory returns preferences or past decisions, honor them without asking the user to repeat.
 
 Honor the project operating hierarchy:
-- Beads (`bd`) is the durable source of truth for tasks; hygiene contract — claim, close, supersede, prune — lives in `rules/common/beads-hygiene.md`. `bd ready` for unblocked work, `bd show <id>` for the active issue.
+- Beads (`bd`) is the durable source of truth for tasks; hygiene contract. claim, close, supersede, prune. lives in `rules/common/beads-hygiene.md`. `bd ready` for unblocked work, `bd show <id>` for the active issue.
 - `plan.md` is the human-readable implementation plan
 - cass-memory via MCP `memory` is for cross-tool/session recall, not task tracking
 
@@ -26,12 +26,12 @@ Use the single-writer rule whenever multiple sessions are active: if two session
 
 ## Classify before acting
 
-Use the code-backed orchestration policy for intent, execution track, specialist selection, escalation, and approval boundaries. Visual deliverables (wireframes, diagrams, decks) are first-class — use real visual tools, not bullet prose.
+Use the code-backed orchestration policy for intent, execution track, specialist selection, escalation, and approval boundaries. Visual deliverables (wireframes, diagrams, decks) are first-class. use real visual tools, not bullet prose.
 
 Execution model:
-- **Immediate** — answer or act directly when no hidden worker is needed.
-- **Focused** — dispatch one bounded specialist path; return in Construct's voice.
-- **Orchestrated** — plan → challenge → build → validate, with tracker-backed slices and explicit file ownership.
+- **Immediate**. answer or act directly when no hidden worker is needed.
+- **Focused**. dispatch one bounded specialist path; return in Construct's voice.
+- **Orchestrated**. plan → challenge → build → validate, with tracker-backed slices and explicit file ownership.
 
 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.
 
@@ -39,9 +39,9 @@ Devil's advocate is mandatory for new architectural directions, AI/agent workflo
 
 `routeRequest` returns three artifacts; honor all three:
 
-1. **Gates** — `framingChallenge`, `externalResearch`, `docAuthoring`
-2. **Contract chain** — typed handoffs from `agents/contracts.json`. Call `agent_contract` MCP tool at handoff.
-3. **Specialist sequence** — dispatch plan with ordering/parallel markers.
+1. **Gates**. `framingChallenge`, `externalResearch`, `docAuthoring`
+2. **Contract chain**. typed handoffs from `agents/contracts.json`. Call `agent_contract` MCP tool at handoff.
+3. **Specialist sequence**. dispatch plan with ordering/parallel markers.
 
 Before DONE: postconditions met · sources cited · framing logged · ADRs have Rejected alternatives.
 
@@ -50,9 +50,9 @@ Before DONE: postconditions met · sources cited · framing logged · ADRs have
 - **Working branch is surfaced every session** at the top of session-start. Restate it before any mutating operation.
 - **Never commit, push, or merge without asking first.** Before `git commit`, `git push`, or `gh pr merge`: state branch, show the proposed message / refspec / PR number verbatim, wait for explicit yes. A batch go-ahead covers a defined sequence; new commits later are their own gate. See `rules/common/commit-approval.md`.
 
-## R&D intake surface
+## Intake surface
 
-Session-start surfaces pending intake at `.cx/intake/pending/<id>.json`. Read with `construct intake show <id>`; the triage block names the primary owner, recommended chain, and next action. For non-trivial signals, plan with `construct graph from-intake <id>` and update node status with evidence (`construct graph status … done --evidence=…`). A node cannot reach `done` without an evidence record. Team / enterprise mode wraps tool calls in the MCP broker — when it returns `ApprovalRequired`, surface the question; never bypass.
+The active profile (`construct profile show`) sets the intake taxonomy. Session-start surfaces pending intake at `.cx/intake/pending/<id>.json`. Read with `construct intake show <id>`; the triage block names the primary owner, recommended chain, and next action. For non-trivial signals, plan with `construct graph from-intake <id>` and update node status with evidence (`construct graph status … done --evidence=…`). A node cannot reach `done` without an evidence record. Team / enterprise mode wraps tool calls in the MCP broker; when it returns `ApprovalRequired`, surface the question and never bypass.
 
 ## Action discipline
 
@@ -73,15 +73,15 @@ Load-bearing state: `AGENTS.md`, `.cx/context.md`/`.json`, `docs/README.md`, `do
 ## Quality gates
 
 After any implementation, dispatch validation before marking done:
-1. cx-reviewer — correctness, regression, coverage
-2. cx-qa — tests pass, coverage meets threshold
+1. cx-reviewer. correctness, regression, coverage
+2. cx-qa. tests pass, coverage meets threshold
 3. cx-security if auth/secrets/user data touched
 
 Do not mark `done` until cx-reviewer and cx-qa return verdicts. BLOCKED or any CRITICAL finding stops shipping.
 
 ## Hard release gates
 
-Run `npm run release:check` before any commit or push — never wait for CI. Commits follow `.gitmessage`; PRs follow `.github/pull_request_template.md`. Full policy: `rules/common/release-gates.md`.
+Run `npm run release:check` before any commit or push. never wait for CI. Commits follow `.gitmessage`; PRs follow `.github/pull_request_template.md`. Full policy: `rules/common/release-gates.md`.
 
 ## Loop guard
 
@@ -91,6 +91,6 @@ Before stopping: surface incomplete tracker-linked plan slices and unmet accepta
 
 ## Drive mode
 
-Activates on word-boundary triggers — `/work:drive`, standalone `drive`, or `full send`. Substring matches do not count.
+Activates on word-boundary triggers. `/work:drive`, standalone `drive`, or `full send`. Substring matches do not count.
 
 On trigger: orchestrated track, skip planning confirmation, continue until verification or a real blocker. State the dispatch plan upfront; brief status at phase transitions. User sees plan and outcomes, not deliberation.

package/platforms/claude/settings.template.json

@@ -460,6 +460,19 @@
         ],
         "id": "stop:optimize-agents",
         "description": "Check performance reviews and auto-optimize low-scoring agents at session end"
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"$HOME/.construct/lib/hooks/session-reflect.mjs\"",
+            "timeout": 5,
+            "async": true
+          }
+        ],
+        "id": "stop:auto-reflect",
+        "description": "Deterministic session-end reflect: extracts a transcript summary into .cx/observations (500ms hard budget; CONSTRUCT_REFLECT_AUTO=off to disable)"
       }
     ],
     "UserPromptSubmit": [

package/rules/common/research.md

@@ -10,7 +10,31 @@ that depends on external facts or evolving internal evidence.
 
 Construct treats research as a reproducible evidence-gathering process, not free-form browsing. If a claim could change decisions, scope, architecture, or roadmap, it must be tied to verifiable evidence.
 
-## 1. Start order
+## 1. Recency discipline
+
+Research always starts from the most recent available evidence.
+
+- Default to sources from the current year before earlier years — always search most-recent-first.
+- For fast-moving topics (AI tools, LLM behavior, cloud APIs, security advisories, market data), treat anything older than 12 months as presumptively stale unless a newer source confirms it is still accurate.
+- When using a search engine or index, always filter or sort by date — do not rely on relevance ranking alone.
+- State the publication or access date for every external source. If a source has no date, treat its confidence as `low` until recency is established another way.
+
+## 2. Domain-specific starting points
+
+Use the narrowest, most authoritative starting point for the research domain:
+
+| Domain | Starting points (most recent first) |
+|---|---|
+| AI tools, LLM behavior, multi-agent | arXiv (cs.AI, cs.SE, cs.CL), ACL Anthology, NeurIPS/ICML/ICLR proceedings, then vendor research blogs |
+| Developer tools, IDE, editor | Stack Overflow Developer Survey (current year), JetBrains Developer Survey, GitHub/Copilot blog, then product changelogs |
+| Security, CVEs, supply chain | NVD, GitHub Security Advisories, OWASP, vendor security blogs (Google Project Zero, Microsoft Security Response), then ProjectDiscovery/Snyk reports |
+| Market data, adoption, ARR | Primary company announcements or SEC filings, then TechCrunch/Bloomberg/WSJ (where citing company sources), then analyst reports |
+| Cloud infra, APIs, SDKs | Official vendor docs for the exact version, changelog, migration guides |
+| Regulatory, compliance, privacy | Primary regulation text, then official guidance from the issuing authority, then law firm analysis |
+
+Tertiary sources (blogs, forums, Q&A, AI-generated summaries) may help locate primaries. They are not sufficient evidence for load-bearing claims.
+
+## 3. Start order
 
 Start with the narrowest authoritative source that can answer the question:
 
@@ -28,9 +52,7 @@ Start with the narrowest authoritative source that can answer the question:
 4. **Tertiary sources last**
    - blogs, forums, Q&A, analyst summaries, AI-generated summaries
 
-Tertiary sources may help discover primary sources. They are not sufficient evidence for load-bearing claims.
-
-## 2. Required metadata for every source
+## 4. Required metadata for every source
 
 Record:
 
@@ -40,9 +62,16 @@ Record:
 - publication date, release date, or access date
 - why this source is relevant
 
-If a source has no date and the topic is time-sensitive, treat confidence as reduced until recency is established another way.
+## 5. URL verification
+
+Every URL cited in a committed document must be verified before the document is published.
+
+- Fetch the URL. Confirm it resolves and the content matches the cited claim.
+- Do not cite aggregate or index pages (e.g., arxiv.org search results, Google Scholar listings) for quantitative claims — cite the specific paper or article URL.
+- If a URL returns a 404, paywall, or redirect loop, find the canonical source or replace the citation.
+- Unverified URLs must be marked `[unverified]` until confirmed.
 
-## 3. Verification rules
+## 6. Verification rules
 
 For each load-bearing claim:
 
@@ -54,7 +83,7 @@ For each load-bearing claim:
 
 Claims about versions, APIs, security, pricing, compatibility, regulations, and timelines must cite the exact version/date basis.
 
-## 4. Reproducibility
+## 7. Reproducibility
 
 Research must be reproducible by another person in the repo.
 
@@ -67,7 +96,7 @@ Record:
 
 If you cannot explain how the answer was obtained, the research is incomplete.
 
-## 5. Evidence thresholds
+## 8. Evidence thresholds
 
 Recommendations must state what evidence threshold was used.
 
@@ -81,27 +110,30 @@ Examples:
 
 If the threshold is not met, the output should recommend more research, a weaker artifact, or a narrower decision.
 
-## 6. Output standard
+## 9. Output standard
 
 Research outputs should include:
 
 - question
 - method
-- sources
+- sources (with dates and classes)
 - findings
 - confidence
 - open questions
 - recommendation or next step
 
-Every substantive finding should point to a source path, URL, or document reference.
+Every substantive finding should point to a verified source path, URL, or document reference.
 
-## 7. Anti-patterns
+## 10. Anti-patterns
 
 Do not:
 
+- start research from older years when more-recent sources are available
 - stop at the first plausible answer
 - cite a blog when the spec or source code is available
+- cite an aggregate or index page when the specific document is available
 - present inference as if the source said it directly
 - ignore conflicting evidence
 - use stale undated material for fast-moving topics without saying so
 - promote weak product evidence into committed requirements
+- include URLs that have not been fetched and confirmed

package/scripts/sync-agents.mjs

@@ -38,6 +38,7 @@ import {
 } from "../lib/mcp-platform-config.mjs";
 import { loadConstructEnv } from "../lib/env-config.mjs";
 import { inlineRoleAntiPatterns, PROMPT_WORD_CAP } from "../lib/role-preload.mjs";
+import { resolveActiveProfile } from "../lib/profiles/loader.mjs";
 import { resolveTiersForPrimary } from "../lib/model-router.mjs";
 import { stampFrontmatter } from "../lib/doc-stamp.mjs";
 
@@ -499,7 +500,17 @@ function buildEntries() {
     });
   }
 
+  // Filter agents by the active profile's role set. RND lists every specialist
+  // so behavior is unchanged for the default; non-RND profiles emit only the
+  // specialists they declare. Profiles whose role list is empty (legacy/test)
+  // fall through to no filter so callers don't get a silent empty registry.
+  const activeProfile = resolveActiveProfile(process.cwd());
+  const profileRoles = Array.isArray(activeProfile?.roles) && activeProfile.roles.length > 0
+    ? new Set(activeProfile.roles)
+    : null;
+
   for (const agent of registry.agents ?? []) {
+    if (profileRoles && !profileRoles.has(agent.name)) continue;
     entries.push({
       ...agent,
       isPersona: false,