@geraldmaron/construct 1.0.6 → 1.0.7

package/lib/project-init-shared.mjs

@@ -235,6 +235,18 @@ Describe the current objective in one clear sentence.
 `;
 }
 
+export function ensureCxDir(rootDir) {
+  const cxDir = path.join(rootDir, '.cx');
+  const contextPath = path.join(cxDir, 'context.md');
+  if (!fs.existsSync(cxDir)) {
+    fs.mkdirSync(cxDir, { recursive: true });
+  }
+  if (!fs.existsSync(contextPath)) {
+    fs.writeFileSync(contextPath, buildContextMarkdown(), 'utf8');
+  }
+  return cxDir;
+}
+
 export function buildContextMarkdown() {
   return `<!--
 .cx/context.md — concise resumable project context for human and agent handoff.

package/lib/provider-capabilities.js

@@ -117,23 +117,36 @@ export function resolveProviderCapabilitiesSync(modelId) {
 }
 
 /**
- * Probe provider for live capabilities (async).
- * Results are cached for 24h.
+ * Probe provider for capabilities and cache the result for 24h.
+ *
+ * Static path (probe=false): resolves capabilities from the adapter's static
+ * declaration. Live path (probe=true): dispatches to the adapter's optional
+ * `probe(modelId)` export — adapters that don't implement it fall back to the
+ * static declaration. Construct itself stays provider-agnostic; per-vendor
+ * probing is the adapter's responsibility.
  *
  * @param {string} modelId
  * @param {object} opts - { probe: boolean }
  * @returns {Promise<object>}
  */
 export async function probeProviderCapabilities(modelId, { probe = false } = {}) {
-  const caps = await resolveProviderCapabilities(modelId);
+  const adapterKey = resolveAdapterKey(modelId);
+  const loader = ADAPTERS[adapterKey] || ADAPTERS.generic;
 
+  let caps;
   if (probe) {
-    // TODO: implement live probing (API call) in Phase A follow-up
-    // For now, just return the static capabilities
+    try {
+      const mod = await loader();
+      caps = typeof mod.probe === 'function'
+        ? await mod.probe(modelId)
+        : mod.capabilities(modelId);
+    } catch {
+      caps = await resolveProviderCapabilities(modelId);
+    }
+  } else {
+    caps = await resolveProviderCapabilities(modelId);
   }
 
-  // Cache by adapter key
-  const adapterKey = resolveAdapterKey(modelId);
   const cache = getCache();
   cache[adapterKey] = caps;
   writeCapabilityCache(cache);

package/lib/providers/auth-manager.mjs

@@ -1,15 +1,23 @@
-// lib/providers/auth-manager.mjs
-// OAuth refresh and token lifecycle management
+/**
+ * lib/providers/auth-manager.mjs — Token lifecycle and refresh dispatch.
+ *
+ * Provider-agnostic store and contract for credential rotation. The actual
+ * refresh flow (OAuth, JWT, vendor-specific) lives in a registered adapter;
+ * dispatch goes to the adapter's `refresh(state)` and the result is persisted
+ * back to the auth store. Adapters lacking a refresh implementation leave the
+ * operator on a reauthenticate-manually path — the safe agnostic default.
+ */
 
 import fs from 'node:fs';
 import path from 'node:path';
 import { homedir } from 'node:os';
 
-const AUTH_DIR = path.join(homedir(), '.construct', 'auth');
-
-try {
-  fs.mkdirSync(AUTH_DIR, { recursive: true, mode: 0o700 });
-} catch { /* ignore */ }
+function authDir() {
+  const home = process.env.HOME || homedir();
+  const dir = path.join(home, '.construct', 'auth');
+  try { fs.mkdirSync(dir, { recursive: true, mode: 0o700 }); } catch { /* ignore */ }
+  return dir;
+}
 
 const PROVIDER_CONFIGS = {
   github: {
@@ -28,9 +36,20 @@ const PROVIDER_CONFIGS = {
   },
 };
 
+const refreshAdapters = new Map();
+
+/**
+ * Register a refresh adapter for a provider. Contract:
+ *   adapter(state) -> Promise<{ success, token, refreshToken?, expiresAt? }>
+ * If no adapter is registered, refresh returns a manual-reauth instruction.
+ */
+export function registerRefreshAdapter(provider, adapter) {
+  if (typeof adapter === 'function') refreshAdapters.set(provider, adapter);
+}
+
 export function loadAuthState(provider) {
   try {
-    const file = path.join(AUTH_DIR, `${provider}.json`);
+    const file = path.join(authDir(), `${provider}.json`);
     if (fs.existsSync(file)) {
       return JSON.parse(fs.readFileSync(file, 'utf8'));
     }
@@ -40,7 +59,7 @@ export function loadAuthState(provider) {
 
 export function saveAuthState(provider, state) {
   try {
-    const file = path.join(AUTH_DIR, `${provider}.json`);
+    const file = path.join(authDir(), `${provider}.json`);
     fs.writeFileSync(file, JSON.stringify(state, null, 2), { mode: 0o600 });
     return true;
   } catch {
@@ -111,16 +130,38 @@ async function refreshToken(provider) {
   if (!config?.refreshable) {
     return { success: false, error: 'Provider does not support refresh' };
   }
-  
+
   const state = loadAuthState(provider);
   if (!state?.refreshToken) {
     return { success: false, error: 'No refresh token available' };
   }
-  
-  // Provider-specific refresh logic would go here
-  // For now, just indicate refresh is needed
-  return {
-    success: false,
-    error: 'Token refresh required - reauthenticate manually',
-  };
+
+  const adapter = refreshAdapters.get(provider);
+  if (!adapter) {
+    return {
+      success: false,
+      error: 'Token refresh required - reauthenticate manually',
+    };
+  }
+
+  try {
+    const result = await adapter(state);
+    if (result?.success && result.token) {
+      const next = {
+        ...state,
+        token: result.token,
+        refreshToken: result.refreshToken || state.refreshToken,
+        expiresAt: result.expiresAt || null,
+        rotatedAt: new Date().toISOString(),
+      };
+      saveAuthState(provider, next);
+      return { success: true, expiresAt: next.expiresAt };
+    }
+    return {
+      success: false,
+      error: result?.error || 'Refresh adapter returned no token',
+    };
+  } catch (err) {
+    return { success: false, error: `Refresh adapter threw: ${err.message}` };
+  }
 }

package/lib/reflect.mjs

@@ -8,10 +8,11 @@
 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 { addObservation, listObservations } 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';
+import { readContextState, contextSummaryLine } from './context-state.mjs';
 
 const HOME = process.env.HOME || process.env.USERPROFILE;
 const USER_ENV_PATH = join(HOME, '.construct', 'config.env');
@@ -47,12 +48,19 @@ export async function runReflectCli(args) {
     target = `knowledge/${target}`;
   }
 
-  // If no summary provided, try to get it from stdin or prompt
+  let summarySource = 'cli';
   if (!summary) {
-    // For now, we'll require explicit summary - in future could read from chat context
-    console.error('Error: --summary=<text> is required to capture improvement feedback');
-    console.error('Example: construct reflect --target=internal --summary="Improve Slack channel intent parsing to handle edge cases"');
-    process.exit(1);
+    const derived = deriveSummaryFromContext(process.cwd());
+    if (derived) {
+      summary = derived;
+      summarySource = 'auto-derived';
+      console.error(`Note: --summary not provided; using auto-derived summary from .cx/context.md and recent observations.`);
+      console.error(`Captured summary: "${summary.slice(0, 180)}${summary.length > 180 ? '…' : ''}"`);
+    } else {
+      console.error('Error: --summary=<text> is required (no .cx/context.md or recent session summaries to derive from)');
+      console.error('Example: construct reflect --target=internal --summary="Improve Slack channel intent parsing to handle edge cases"');
+      process.exit(1);
+    }
   }
 
   // Resolve the knowledge directory for this target
@@ -110,15 +118,14 @@ export async function runReflectCli(args) {
   // Write the file
   writeFileSync(filePath, content);
 
-  // Record an observation about this feedback
-  const observationSummary = `[reflect] Improvement feedback captured: ${summary.slice(0, 100)}${summary.length > 100 ? '...' : ''}`;
+  const observationSummary = `[reflect] Improvement feedback captured (${summarySource}): ${summary.slice(0, 100)}${summary.length > 100 ? '...' : ''}`;
   addObservation(process.cwd(), {
     role: 'construct',
-    category: 'insight', // Feedback is typically an insight unless it's about a problem
+    category: 'insight',
     summary: observationSummary,
-    content: `Feedback captured via construct reflect:\n\n${summary}\n\nStored as: ${filePath}\nTarget: ${knowledgeSubdir}/`,
-    tags: ['reflect', 'improvement-feedback', `knowledge:${knowledgeSubdir}`],
-    confidence: 0.9,
+    content: `Feedback captured via construct reflect (${summarySource}):\n\n${summary}\n\nStored as: ${filePath}\nTarget: ${knowledgeSubdir}/`,
+    tags: ['reflect', 'improvement-feedback', `knowledge:${knowledgeSubdir}`, `source:${summarySource}`],
+    confidence: summarySource === 'auto-derived' ? 0.65 : 0.9,
     source: 'reflect-command',
   });
 
@@ -186,6 +193,36 @@ export async function runReflectAuto({ transcriptPath, cwd, sessionId, durationM
   return result?.id ?? null;
 }
 
+/**
+ * Derive a one-paragraph reflect summary from durable session state — the
+ * context.md digest first, then the most recent session-summary observation.
+ * Returns null when neither source yields useful content.
+ */
+export function deriveSummaryFromContext(cwd) {
+  const parts = [];
+
+  try {
+    const state = readContextState(cwd);
+    const line = contextSummaryLine(state);
+    if (line && line.trim().length > 20) parts.push(line.trim());
+  } catch { /* best effort */ }
+
+  try {
+    const recent = listObservations(cwd, { limit: 5 }) || [];
+    const sessionSummary = recent.find((o) => Array.isArray(o.tags) && o.tags.includes('session-summary'));
+    if (sessionSummary?.summary) {
+      const text = String(sessionSummary.summary).replace(/^\[[^\]]+\]\s*/, '').trim();
+      if (text.length > 20 && !parts.some((p) => p.includes(text.slice(0, 40)))) {
+        parts.push(text);
+      }
+    }
+  } catch { /* best effort */ }
+
+  if (parts.length === 0) return null;
+  const joined = parts.join(' — ');
+  return joined.length > 600 ? joined.slice(0, 580) + '…' : joined;
+}
+
 function safeProject(cwd) {
   try { return basename(cwd) || null; } catch { return null; }
 }

package/lib/server/index.mjs

@@ -8,6 +8,7 @@
  * Runs on port 4242 (overridable via PORT env var), bound to 127.0.0.1.
  */
 import { createServer } from 'http';
+import { registerBoundary } from '../boundary.mjs';
 import { readFileSync, writeFileSync, statSync, watch, existsSync, readdirSync, mkdirSync, renameSync, chmodSync, appendFileSync } from 'fs';
 import { spawnSync } from 'child_process';
 import { join, extname, relative, normalize, dirname } from 'path';
@@ -1115,44 +1116,36 @@ const server = createServer(async (req, res) => {
       const chunks = [];
       await new Promise((resolve, reject) => { req.on('data', c => chunks.push(c)); req.on('end', resolve); req.on('error', reject); });
       const body = JSON.parse(Buffer.concat(chunks).toString('utf8') || '{}');
-      
-      const { parentInstance, parentUrl, childInstanceId } = body;
-      
+
+      const { parentInstance, parentUrl, childInstanceId, nonce, signature } = body;
+
       if (!parentInstance || !parentUrl) {
         res.writeHead(400, { 'Content-Type': 'application/json' });
         res.end(JSON.stringify({ error: 'parentInstance and parentUrl are required' }));
         return;
       }
-      
-      // In a real implementation, this would:
-      // - Validate the parent is a legitimate Construct instance
-      // - Store the parent registration in a boundary configuration
-      // - Set up communication channels between parent and child
-      // - Configure isolation boundaries
-      
-      // For now, just acknowledge the registration
-      const configDir = join(HOME, '.construct');
-      if (!existsSync(configDir)) {
-        mkdirSync(configDir, { recursive: true });
-      }
-      
-      const boundaryConfig = {
+
+      const result = await registerBoundary({
         parentInstance,
         parentUrl,
-        childInstanceId: childInstanceId || env.CONSTRUCT_INSTANCE_ID || 'default',
-        registeredAt: new Date().toISOString(),
-        boundaryVersion: '1.0'
-      };
-      
-      const boundaryConfigPath = join(configDir, 'boundary-config.json');
-      writeFileSync(boundaryConfigPath, JSON.stringify(boundaryConfig, null, 2));
-      
+        childInstanceId: childInstanceId || process.env.CONSTRUCT_INSTANCE_ID || 'default',
+        nonce,
+        signature,
+        sharedSecret: process.env.CONSTRUCT_BOUNDARY_SECRET || null,
+      });
+
+      if (!result.ok) {
+        res.writeHead(result.status || 400, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: result.error }));
+        return;
+      }
+
       res.writeHead(200, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ 
+      res.end(JSON.stringify({
         success: true,
         message: 'Boundary registration accepted',
-        boundaryConfig,
-        boundaryConfigPath
+        boundaryConfig: result.config,
+        boundaryConfigPath: result.path,
       }));
     } catch (err) {
       res.writeHead(500, { 'Content-Type': 'application/json' });
@@ -2243,3 +2236,4 @@ process.on('SIGINT', () => shutdown('SIGINT'));
 onEmbedNotification((event) => {
   notifyClients({ type: 'toast', ...event });
 });
+

package/lib/session-store.mjs

@@ -19,6 +19,7 @@ import path from "node:path";
 import { cosineSimilarity, rankByBm25 } from "./storage/embeddings.mjs";
 import { embedSync as embedText } from "./storage/embeddings-legacy.mjs";
 import { withFileLockSync } from "./storage/file-lock.mjs";
+import { ensureCxDir } from "./project-init-shared.mjs";
 
 const SESSIONS_DIR = ".cx/sessions";
 const INDEX_FILE = "index.json";
@@ -29,7 +30,8 @@ const MAX_DECISIONS = 20;
 const MAX_FILES = 50;
 const MAX_OPEN_QUESTIONS = 10;
 
-function ensureDir(dir) {
+function ensureDir(dir, rootDir = null) {
+  if (rootDir) ensureCxDir(rootDir);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
 }
 
@@ -52,7 +54,7 @@ function readVectors(rootDir) {
 }
 
 function writeVectors(rootDir, records) {
-  ensureDir(sessionsDir(rootDir));
+  ensureDir(sessionsDir(rootDir), rootDir);
   const target = vectorsPath(rootDir);
   withFileLockSync(target, () => {
     fs.writeFileSync(target, JSON.stringify(records.slice(0, MAX_INDEX_ENTRIES), null, 2) + "\n");
@@ -86,7 +88,7 @@ function readIndex(rootDir) {
 }
 
 function writeIndex(rootDir, entries) {
-  ensureDir(sessionsDir(rootDir));
+  ensureDir(sessionsDir(rootDir), rootDir);
   const trimmed = entries.slice(0, MAX_INDEX_ENTRIES);
   const target = indexPath(rootDir);
   withFileLockSync(target, () => {
@@ -137,7 +139,7 @@ export function createSession(rootDir, {
     taskSnapshot: [],
   };
 
-  ensureDir(sessionsDir(rootDir));
+  ensureDir(sessionsDir(rootDir), rootDir);
   fs.writeFileSync(
     path.join(sessionsDir(rootDir), `${id}.json`),
     JSON.stringify(record, null, 2) + "\n"

package/lib/setup.mjs

@@ -420,7 +420,7 @@ function ensureOpenCodeConfig() {
 // repo but never executed by git. Idempotent: leaves a user-set value alone
 // rather than clobbering it.
 
-function ensureGitHooksPath({ cwd = process.cwd() } = {}) {
+export function ensureGitHooksPath({ cwd = process.cwd() } = {}) {
   const hooksDir = path.join(cwd, '.beads', 'hooks');
   if (!fs.existsSync(path.join(hooksDir, 'pre-commit'))) {
     return { status: 'skipped', reason: 'no .beads/hooks/pre-commit in this directory' };
@@ -435,10 +435,21 @@ function ensureGitHooksPath({ cwd = process.cwd() } = {}) {
   if (currentValue === desired) {
     return { status: 'ok', message: 'core.hooksPath already wired to .beads/hooks' };
   }
-  if (currentValue && currentValue !== desired) {
+
+  // Treat the git default (`.git/hooks` or an absolute path to it) as
+  // equivalent to unset. A user who has accepted the default has not made an
+  // active choice that justifies "leave alone" semantics; without this branch
+  // an install that happens to land while `.git/hooks` is already in play
+  // leaves policy gates inactive permanently.
+  const isGitDefault =
+    !currentValue ||
+    currentValue === '.git/hooks' ||
+    currentValue === path.join(cwd, '.git', 'hooks') ||
+    currentValue.replace(/\/+$/, '').endsWith(`${path.sep}.git${path.sep}hooks`);
+  if (!isGitDefault) {
     return {
       status: 'warning',
-      message: `core.hooksPath is set to '${currentValue}'. Leaving alone — set to '.beads/hooks' to activate Construct policy gates.`,
+      message: `core.hooksPath is set to '${currentValue}'. Leaving alone. Set to '.beads/hooks' to activate Construct policy gates.`,
     };
   }
   const result = spawnSync('git', ['config', 'core.hooksPath', desired], { cwd, stdio: 'pipe', encoding: 'utf8' });

package/lib/telemetry/client.mjs

@@ -10,6 +10,7 @@ import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
 
 import { createIngestClient } from './ingest.mjs';
+import { ensureCxDir } from '../project-init-shared.mjs';
 
 const DEFAULT_MAX_BATCH = 50;
 
@@ -55,7 +56,10 @@ function appendLocalTelemetry(type, body, { rootDir, env = process.env, onError
   const projectRoot = resolveProjectRoot({ rootDir, env });
   const dir = join(projectRoot, '.cx', 'traces');
   try {
-    if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+    if (!existsSync(dir)) {
+      ensureCxDir(projectRoot);
+      mkdirSync(dir, { recursive: true });
+    }
     appendFileSync(join(dir, `${traceShard()}.jsonl`), `${JSON.stringify({
       traceId: body?.traceId || body?.id || randomUUID(),
       spanId: body?.id || randomUUID(),

package/lib/version.mjs

@@ -0,0 +1,51 @@
+/**
+ * lib/version.mjs — Single source of truth for the installed Construct version.
+ *
+ * Reads package.json once per process and caches. Surfaces:
+ *   - bin/construct (`--version`, `construct version`)
+ *   - construct status (header)
+ *   - migration runner (compatibility check against artifact schema versions)
+ *   - doctor watchers (advisory drift against published npm tag)
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const PKG_PATH = join(ROOT, 'package.json');
+
+let _cached = null;
+
+export function getInstalledVersion() {
+  if (_cached) return _cached;
+  try {
+    const pkg = JSON.parse(readFileSync(PKG_PATH, 'utf8'));
+    _cached = { version: pkg.version || '0.0.0', name: pkg.name || 'construct', pkgPath: PKG_PATH };
+  } catch {
+    _cached = { version: '0.0.0', name: 'construct', pkgPath: PKG_PATH };
+  }
+  return _cached;
+}
+
+/**
+ * Parse a semver string into { major, minor, patch }. Returns null on failure.
+ */
+export function parseSemver(s) {
+  const match = String(s || '').match(/^(\d+)\.(\d+)\.(\d+)/);
+  if (!match) return null;
+  return { major: Number(match[1]), minor: Number(match[2]), patch: Number(match[3]) };
+}
+
+/**
+ * Compare two semver strings. Returns -1 / 0 / 1.
+ */
+export function compareSemver(a, b) {
+  const pa = parseSemver(a);
+  const pb = parseSemver(b);
+  if (!pa || !pb) return 0;
+  if (pa.major !== pb.major) return pa.major < pb.major ? -1 : 1;
+  if (pa.minor !== pb.minor) return pa.minor < pb.minor ? -1 : 1;
+  if (pa.patch !== pb.patch) return pa.patch < pb.patch ? -1 : 1;
+  return 0;
+}

package/lib/worker/trace.mjs

@@ -31,6 +31,7 @@ import { randomBytes } from 'node:crypto';
 import path from 'node:path';
 
 import { createTelemetryClient } from '../telemetry/client.mjs';
+import { ensureCxDir } from '../project-init-shared.mjs';
 
 const TRACE_SUBDIR = '.cx/traces';
 
@@ -150,7 +151,10 @@ export function emitTraceEvent({
   }
 
   const dir = traceDir(rootDir);
-  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  if (!existsSync(dir)) {
+    ensureCxDir(rootDir);
+    mkdirSync(dir, { recursive: true });
+  }
 
   const event = {
     traceId: traceId || newTraceId(),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geraldmaron/construct",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "type": "module",
   "description": "Construct — agent orchestration layer for OpenCode, Claude Code, and other coding surfaces",
   "bin": {
@@ -50,12 +50,15 @@
     "docs:dev": "npm --prefix apps/docs run dev",
     "docs:build": "npm --prefix apps/docs run build",
     "lint:comments": "node ./bin/construct lint:comments",
+    "lint:contracts": "node ./bin/construct lint:contracts",
+    "lint:agents": "node ./bin/construct lint:agents",
     "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:gate": "node --test tests/functional/release-gate.functional.test.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",

package/personas/construct.md

@@ -5,7 +5,9 @@ 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 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`.
 
 ## Start of every session
 

package/rules/common/development-workflow.md

@@ -8,8 +8,9 @@ git operations. References testing.md, code-review.md, git-workflow.md.
 
 ## Feature Implementation Workflow
 
-0. **Research & Reuse** _(mandatory before any new implementation)_
+0. **Research & Reuse** _(mandatory before any new implementation or artifact)_
    - **Search existing code first:** Look for existing implementations, templates, and patterns before writing anything new.
+   - **Search existing artifacts:** Before authoring a doc, rule, template, strategy, PRD, ADR, or RFC, audit what already exists. See [review-before-change.md](review-before-change.md) for the audit checklist. Extend or supersede; do not duplicate.
    - **Check docs:** Confirm API behavior, package usage, and version-specific details before implementing.
    - **Check package registries:** npm, PyPI, crates.io before writing utility code.
    - Prefer adopting a proven approach over writing net-new code.

package/rules/common/no-fabrication.md

@@ -0,0 +1,69 @@
+<!--
+rules/common/no-fabrication.md: canonical anti-fabrication policy for Construct.
+
+Defines the trust contract between operators and the system: outputs stick to
+source, gaps stay visible, and confidence reflects evidence. Applies to every
+specialist, every artifact, and every summary — intake processing, document
+evaluation, knowledge writing, plan drafting, review verdicts, handoffs.
+
+Sibling rules: research.md (evidence hierarchy), framing.md (execution
+artifacts are not sources), comments.md (banned voice patterns).
+-->
+# No-Fabrication Policy
+
+Fabrication is the single largest threat to trust in an agent system. A persona that invents a customer quote, sharpens a vague signal into a confident assertion, or papers over a gap with plausible-sounding prose corrupts every artifact downstream. This rule applies to **every output** Construct produces: intake summaries, classification rationales, PRDs, ADRs, RFCs, knowledge notes, handoffs, review verdicts, plan entries, beads issues, MCP tool responses, dashboard text.
+
+## 1. Stick to source
+
+- Every load-bearing claim must trace to a source the reader can re-verify. Cite with `[source: path#anchor]`, `[source: intake-<id>]`, `[source: bd-<id>]`, `[source: <commit-sha>]`, or a fetched URL with the date the fetch happened.
+- If a fact is not in the source you have access to, write `unknown` or `[unverified]`. Do not paper over the gap with prose that sounds confident.
+- Never invent: customer names, quotes, ticket IDs, commit hashes, percentages, dates, file paths, function names, API surfaces, dependency names, version numbers.
+
+## 2. Preserve ambiguity
+
+- A vague signal stays vague in the artifact. If the intake says "users are frustrated with the dashboard," the PRD says "users are frustrated with the dashboard [source: intake-xxx]" — not "users want sub-200ms p95 dashboard latency."
+- When a source is ambiguous, list the possible interpretations and tag the chosen reading as inference, not observation.
+- Do not promote inference to observation. `X happened` requires evidence the event happened. `X likely means Y` requires the inference to be marked as such.
+
+## 3. Distinguish observation from inference
+
+- Observation: directly verifiable from the source. Format: bare statement with citation.
+- Inference: a conclusion drawn from one or more observations. Format: prefixed with `inference:` or `[inferred]`, and the supporting observations must be cited.
+- Speculation (no supporting observation): not allowed in artifacts. If you must raise a hypothesis, write it as a question, not an assertion.
+
+## 4. Calibrate confidence honestly
+
+- Confidence in artifacts and observation records reflects evidence strength, not authorial conviction. Single-source claims, secondary sources, and inferred conclusions get lower confidence than primary-source observations.
+- Words that smuggle confidence without evidence — `clearly`, `obviously`, `undoubtedly`, `definitely`, `certainly`, `surely` — are banned from artifact bodies. Replace with an explicit citation or remove.
+- Quantitative claims (`30% faster`, `5x improvement`, `90th percentile latency`) require an inline source. Hand-wave percentages are fabrication.
+
+## 5. Don't mind-read users or customers
+
+- `Users want X`, `customers expect Y`, `everyone agrees Z` require a citation to the source where the user or customer said so (interview transcript, support ticket, survey, observed behavior). Without the citation, the claim is fabrication.
+- Speculative product-vision language is allowed only in clearly-marked hypothesis or alternative sections, never in observation or requirements sections.
+
+## 6. Surface uncertainty as a question, not an assertion
+
+- When you don't know, ask. A persona that doesn't know whether a regression touched the auth flow asks for the diff before claiming it did. A reviewer who can't tell if a test covers a branch asks for the coverage report.
+- "I don't have access to X" is a valid output. Pretending to have access is fabrication.
+
+## 7. Embellishment is fabrication
+
+- Adding plausible-but-unverified detail to a summary, classification rationale, or handoff is fabrication, even when the additions feel innocuous.
+- The intake classifier's `rationale` field lists the exact keywords matched. Downstream personas must not embellish the rationale into a richer narrative the classifier did not produce.
+- Session summaries derive from observable session artifacts (context, observations, commits). Do not include events the transcript does not record.
+
+## 8. When in doubt, say less
+
+- A shorter, accurate artifact beats a longer artifact padded with unverified plausibility.
+- Sections that lack source material should be omitted, not filled with speculation. An ADR without a "Rejected alternatives" section because no alternatives were considered is better than an ADR with invented alternatives.
+
+## Enforcement
+
+- `lib/comment-lint.mjs` enforces a subset of these patterns on artifact paths (`docs/prd/**`, `docs/adr/**`, `docs/rfc/**`, `docs/research/**`, `.cx/knowledge/**`, `.cx/handoffs/**`, `.cx/research/**`). PostToolUse warns; `npm run lint:comments`, `construct lint:comments`, and the release gate block.
+- `agents/contracts.json` postconditions check structural requirements (mandatory sections, intake traceability, citation density). `lib/contracts/validate.mjs#validateHandoff` blocks handoffs that fail validation when `CONSTRUCT_CONTRACT_ENFORCEMENT=block`.
+- `construct intake done <id> --output=<path>` stamps `intake_id`, `intake_confidence`, and `intake_rationale` into the artifact's frontmatter so every intake-derived artifact carries verifiable provenance.
+
+## Bypass
+
+There is no bypass. If a check is wrong, fix the check (`rules/common/no-fabrication.md`, the pattern bank in `lib/comment-lint.mjs`, or the contract postcondition). Do not work around the gate.