@geraldmaron/construct 1.0.6 → 1.0.7

package/lib/auto-docs.mjs

@@ -158,10 +158,10 @@ function buildAgentsTable(rootDir) {
   const agents = registry.agents ?? registry;
   if (!Array.isArray(agents)) return '';
 
-  const rows = ['| Agent | Tier | Purpose |', '|---|---|---|'];
+  const rows = ['| Specialist | Tier | Purpose |', '|---|---|---|'];
   for (const agent of agents.slice(0, 30)) {
-    const name = agent.id ?? agent.name ?? 'n/a';
-    const tier = agent.tier ?? agent.model_tier ?? 'n/a';
+    const name = agent.name ?? agent.id ?? 'n/a';
+    const tier = agent.modelTier ?? agent.tier ?? agent.model_tier ?? 'n/a';
     // Strip em-dashes from descriptions so the prose lint stays clean across
     // AUTO regen. Em-dashes are allowed in the registry's source descriptions
     // but never in the rendered markdown.
@@ -195,7 +195,7 @@ export async function regenerateDocs({ rootDir, check = false } = {}) {
       },
     },
     {
-      file: path.join(rootDir, 'docs', 'concepts', 'architecture.md'),
+      file: path.join(rootDir, 'docs', 'concepts', 'architecture.mdx'),
       regions: {
         agents: buildAgentsTable(rootDir),
       },
@@ -396,13 +396,13 @@ function renderAgentsPage(rootDir) {
   if (!table) return null;
   return [
     '---',
-    'title: Agents',
-    'description: The 28 cx-* specialists plus the construct persona. Generated from agents/registry.json.',
+    'title: Specialists',
+    'description: The 28 specialists behind the construct persona. Generated from agents/registry.json.',
     '---',
     '',
     '> Generated from `agents/registry.json`. Re-run `construct docs:site` to refresh.',
     '',
-    'Construct ships one persona (`construct`) plus 28 specialists. Each specialist has a role, model tier, and prompt that defines its decision authority. Specialists are addressable directly when you want a focused conversation; for everyday work, address `@construct` and let it route.',
+    'Construct ships one persona (`construct`) and 28 specialists behind it. You address `@construct` for all everyday work; it routes to specialists internally. Each specialist has a role, model tier, and prompt file that defines its decision authority.',
     '',
     table,
     '',

package/lib/boundary.mjs

@@ -0,0 +1,126 @@
+/**
+ * lib/boundary.mjs — Authenticated parent/child boundary registration.
+ *
+ * Verifies a parent Construct instance is reachable, validates an HMAC
+ * signature over `childInstanceId|nonce` when a shared secret is configured,
+ * and persists the binding to ~/.construct/boundary.json (mode 0600). A
+ * different parent rotates the registration only when explicitly allowed via
+ * CONSTRUCT_BOUNDARY_ALLOW_OVERRIDE=1; prior configs are archived alongside
+ * the active one. Exposed as a standalone module so the dashboard endpoint
+ * and the functional tests share the same logic.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir } from 'node:os';
+import { createHmac, timingSafeEqual, randomBytes } from 'node:crypto';
+import { request as httpRequest } from 'node:http';
+import { request as httpsRequest } from 'node:https';
+
+export const BOUNDARY_VERSION = '1.0';
+
+function boundaryDir(home = homedir()) {
+  return join(home, '.construct');
+}
+
+export function boundaryConfigPath(home = homedir()) {
+  return join(boundaryDir(home), 'boundary.json');
+}
+
+export async function registerBoundary({
+  parentInstance,
+  parentUrl,
+  childInstanceId,
+  nonce,
+  signature,
+  sharedSecret = null,
+  home = homedir(),
+  allowOverride = process.env.CONSTRUCT_BOUNDARY_ALLOW_OVERRIDE === '1',
+  probe = probeParent,
+}) {
+  if (!parentInstance || !parentUrl) {
+    return { ok: false, status: 400, error: 'parentInstance and parentUrl are required' };
+  }
+  if (!childInstanceId) {
+    return { ok: false, status: 400, error: 'childInstanceId is required' };
+  }
+
+  if (sharedSecret) {
+    if (!nonce || !signature) {
+      return { ok: false, status: 401, error: 'nonce and signature are required when a shared secret is configured' };
+    }
+    const expected = createHmac('sha256', sharedSecret).update(`${childInstanceId}|${nonce}`).digest('hex');
+    const a = Buffer.from(expected, 'hex');
+    let b;
+    try { b = Buffer.from(String(signature), 'hex'); } catch { return { ok: false, status: 401, error: 'invalid signature encoding' }; }
+    if (a.length !== b.length || !timingSafeEqual(a, b)) {
+      return { ok: false, status: 401, error: 'signature mismatch' };
+    }
+  }
+
+  const reachable = await probe(parentUrl);
+  if (!reachable.ok) {
+    return { ok: false, status: 502, error: `parent unreachable: ${reachable.error}` };
+  }
+
+  const dir = boundaryDir(home);
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+  const cfgPath = boundaryConfigPath(home);
+
+  let prior = null;
+  if (existsSync(cfgPath)) {
+    try { prior = JSON.parse(readFileSync(cfgPath, 'utf8')); } catch { prior = null; }
+  }
+
+  if (prior && prior.parentInstance && prior.parentInstance !== parentInstance) {
+    if (!allowOverride) {
+      return {
+        ok: false,
+        status: 409,
+        error: `child already bound to parent '${prior.parentInstance}'; set CONSTRUCT_BOUNDARY_ALLOW_OVERRIDE=1 to rotate`,
+      };
+    }
+    const archivePath = join(dir, `boundary.${Date.now()}.json`);
+    try { writeFileSync(archivePath, JSON.stringify(prior, null, 2)); } catch { /* archive is best effort */ }
+  }
+
+  const config = {
+    parentInstance,
+    parentUrl,
+    childInstanceId,
+    registeredAt: new Date().toISOString(),
+    rotatedFrom: prior?.parentInstance || null,
+    nonce: nonce || randomBytes(16).toString('hex'),
+    boundaryVersion: BOUNDARY_VERSION,
+  };
+
+  writeFileSync(cfgPath, JSON.stringify(config, null, 2), { mode: 0o600 });
+  return { ok: true, config, path: cfgPath };
+}
+
+export function probeParent(parentUrl) {
+  return new Promise((resolve) => {
+    let parsed;
+    try { parsed = new URL(parentUrl); } catch { return resolve({ ok: false, error: 'invalid URL' }); }
+    if (!/^https?:$/.test(parsed.protocol)) return resolve({ ok: false, error: 'unsupported protocol' });
+    const fn = parsed.protocol === 'https:' ? httpsRequest : httpRequest;
+    const req = fn({
+      method: 'HEAD',
+      protocol: parsed.protocol,
+      hostname: parsed.hostname,
+      port: parsed.port,
+      path: parsed.pathname || '/',
+      timeout: 3000,
+    }, (response) => {
+      resolve({ ok: response.statusCode < 500 });
+      response.resume();
+    });
+    req.on('timeout', () => { req.destroy(); resolve({ ok: false, error: 'timeout' }); });
+    req.on('error', (err) => resolve({ ok: false, error: err.message }));
+    req.end();
+  });
+}
+
+export function signBoundaryRequest({ childInstanceId, nonce, sharedSecret }) {
+  return createHmac('sha256', sharedSecret).update(`${childInstanceId}|${nonce}`).digest('hex');
+}

package/lib/cache-strategy-google.js

@@ -1,17 +1,34 @@
 /**
- * lib/cache-strategy-google.js — Google Gemini cache strategy.
+ * lib/cache-strategy-google.js — Google Gemini cache strategy (agnostic skeleton).
  *
- * Google uses cachedContent API (resource-based caching, not annotations).
- * Cache TTL: 1h via cachedContent resource.
- * Requires separate API call to create/update cached content.
+ * Gemini uses a resource-based cachedContent API rather than per-message
+ * annotations. Construct does not own that integration: this module exposes
+ * the same surface as the other cache-strategy adapters and resolves cached
+ * resources via a pluggable resolver. The default resolver returns null
+ * (no cached resource), which is the safe agnostic default — callers will
+ * fall through to a fresh request. Provider plugins or operators can register
+ * a resolver via `setCachedContentResolver` to enable resource caching.
  */
 import { estimateTokens } from './token-engine.js';
 
 const GEMINI_CACHE_ENDPOINT = 'https://generativelanguage.googleapis.com/v1';
 
+let cachedContentResolver = null;
+
+/**
+ * Register a resolver responsible for producing a cachedContent resource name
+ * for a given system prompt. Contract:
+ *   resolver({ systemText, caps, apiKey, modelId }) -> Promise<string|null>
+ * Returning null means no cached resource is available; the annotation is
+ * omitted and the request proceeds without a cached prefix.
+ */
+export function setCachedContentResolver(resolver) {
+  cachedContentResolver = typeof resolver === 'function' ? resolver : null;
+}
+
 /**
- * Annotate prompt structure for Google Gemini models.
- * Note: Gemini uses cachedContent API, not message annotations.
+ * Annotate prompt structure for Google Gemini models. Returns the shared
+ * annotation shape that every cache-strategy adapter emits.
  *
  * @param {object} promptStructure - { system, messages }
  * @param {object} caps - Provider capabilities
@@ -22,12 +39,10 @@ export async function annotate(promptStructure, caps, { apiKey, modelId } = {})
   const { system, messages } = promptStructure || {};
 
   let cachedContentName = null;
-
-  if (apiKey && system) {
+  if (cachedContentResolver && apiKey && system) {
     try {
-      cachedContentName = await createCachedContent(system, caps, apiKey, modelId);
-    } catch (err) {
-    }
+      cachedContentName = await cachedContentResolver({ systemText: system, caps, apiKey, modelId });
+    } catch { /* resolver failure is non-fatal — fall through with no annotation */ }
   }
 
   return {
@@ -49,26 +64,6 @@ export async function annotate(promptStructure, caps, { apiKey, modelId } = {})
   };
 }
 
-async function createCachedContent(systemText, caps, apiKey, modelId) {
-  // POST to https://generativelanguage.googleapis.com/v1/cachedContents
-  // Body: { model: 'gemini-1.5-pro', contents: [{ parts: [{ text: systemText }] }] }
-  // Returns: { name: 'cachedContents/abc123' }
-
-  const model = extractModelName(modelId);
-  const url = `${GEMINI_CACHE_ENDPOINT}/cachedContents?key=${apiKey}`;
-
-  // This is async but we don't want to block dispatch
-  // In production, this should be pre-cached
-  // For now, return null (defer to Phase C follow-up with live probing)
-  return null;
-}
-
-function extractModelName(modelId) {
-  const id = String(modelId || '').toLowerCase();
-  const match = id.match(/google\/(gemini-[^\/]+)/);
-  return match ? match[1] : 'gemini-1.5-pro';
-}
-
 export async function capabilities() {
   return {
     supportsAnnotations: false,

package/lib/comment-lint.mjs

@@ -29,10 +29,29 @@ const MD_HEADER_GLOBS = [
   /^commands\//,
 ];
 
+// Artifact paths receive an additional prose-lint pass for fabrication patterns
+// (manufactured confidence, hand-wave percentages, mind-reading, speculation).
+// Scope is deliberately narrow — READMEs, cookbook, concepts, and reference are
+// unaffected. The patterns live in BANNED_ARTIFACT below; the severity (block
+// vs warn) is controlled by CONSTRUCT_ARTIFACT_LINT_MODE.
+const ARTIFACT_PATH_GLOBS = [
+  /^docs\/prd\//,
+  /^docs\/adr\//,
+  /^docs\/rfc\//,
+  /^docs\/research\//,
+  /^\.cx\/knowledge\//,
+  /^\.cx\/handoffs\//,
+  /^\.cx\/research\//,
+];
+
 function relPath(rootDir, absPath) {
   return path.relative(rootDir, absPath).replace(/\\/g, '/');
 }
 
+function isArtifactPath(rel) {
+  return ARTIFACT_PATH_GLOBS.some((r) => r.test(rel));
+}
+
 function requiresHeader(rel) {
   const ext = path.extname(rel);
   if (['.yaml', '.yml', '.json', '.jsonl', '.toml'].includes(ext)) return { required: false, type: null };
@@ -88,6 +107,13 @@ const BANNED = [
   // step markers — only flag in `//` comments. Ordered lists are
   // conventional inside JSDoc decision-tree and flow documentation.
   { pattern: /\/\/\s+\d+\.\s+\w/, label: 'step marker: use function names or block structure instead of "// 1. Step"' },
+  // deferred-implementation wording: signals incomplete work that should
+  // either ship or be removed before release.
+  { pattern: new RegExp(`${CMT}.*\\bphase\\s+[abc]\\s+follow-?up\\b`, 'i'), label: 'deferred implementation: "Phase X follow-up" — ship it or remove it' },
+  { pattern: new RegExp(`${CMT}.*\\bin a real implementation\\b`, 'i'), label: 'deferred implementation: "in a real implementation" — implement the contract honestly' },
+  { pattern: new RegExp(`${CMT}.*\\bwould go here\\b`, 'i'), label: 'deferred implementation: "would go here" — implement or delete the placeholder' },
+  { pattern: new RegExp(`${CMT}.*\\bcoming soon\\b`, 'i'), label: 'deferred implementation: "coming soon" — not a release-ready statement' },
+  { pattern: new RegExp(`${CMT}.*\\bnot yet supported\\b`, 'i'), label: 'deferred implementation: "not yet supported" — document the supported contract instead' },
   // markdown equivalents
   { pattern: /<!--.*\b(?:added for|added recently|just added|new:)\b.*-->/i, label: 'point-in-time in markdown comment' },
   { pattern: /<!--.*\b(?:used by|called from|only consumer)\b.*-->/i, label: 'caller reference in markdown comment' },
@@ -102,16 +128,111 @@ const BANNED = [
 const BANNED_CHECK_SKIP = [
   'lib/comment-lint.mjs',
   'rules/common/comments.md',
+  'rules/common/no-fabrication.md',
   'tests/comment-lint.test.mjs',
   'commands/work/clean.md',
   'skills/utility/clean-code.md',
 ];
 
+// Artifact-prose patterns. Scoped to ARTIFACT_PATH_GLOBS. Each entry can mark
+// requireCitation: true — in that case the violation is suppressed when a
+// citation (`[source: …]`, http URL, or footnote ref) appears in the same line
+// or within 2 lines of context.
+const BANNED_ARTIFACT = [
+  {
+    pattern: /\b(?:clearly|obviously|undoubtedly|definitely|certainly|surely)\b/i,
+    label: 'manufactured confidence: "clearly/obviously/undoubtedly/etc" smuggles certainty without evidence (no-fabrication §4)',
+  },
+  {
+    pattern: /\b\d{1,3}\s*%/,
+    label: 'unattributed percentage: quantitative claims require a [source: …] citation (no-fabrication §4)',
+    requireCitation: true,
+  },
+  {
+    pattern: /\b(?:users|customers|everyone)\s+(?:want|expect|prefer|agree|need)\b/i,
+    label: 'customer mind-reading: "users want / customers expect / everyone agrees" requires a [source: …] citation (no-fabrication §5)',
+    requireCitation: true,
+  },
+  {
+    pattern: /\b(?:will\s+(?:likely|probably)|should\s+improve|expected\s+to\s+(?:improve|reduce|increase|drop|rise))\b/i,
+    label: 'speculative projection: future-tense claims need a baseline + projection source (no-fabrication §3, §4)',
+    requireCitation: true,
+  },
+];
+
 function isBannedCheckSkipped(filePath) {
   if (!filePath) return false;
   return BANNED_CHECK_SKIP.some((suffix) => filePath.endsWith(suffix));
 }
 
+// Track fenced code blocks ( ``` … ``` ) and YAML frontmatter ( --- … --- )
+// so artifact-prose patterns inside code or metadata are not flagged.
+function buildSkipMap(lines) {
+  const skip = new Array(lines.length).fill(false);
+  let inFence = false;
+  let inFrontmatter = false;
+  let frontmatterClosed = false;
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (i === 0 && line.trim() === '---') {
+      inFrontmatter = true;
+      skip[i] = true;
+      continue;
+    }
+    if (inFrontmatter) {
+      skip[i] = true;
+      if (line.trim() === '---') {
+        inFrontmatter = false;
+        frontmatterClosed = true;
+      }
+      continue;
+    }
+    if (/^```/.test(line)) {
+      inFence = !inFence;
+      skip[i] = true;
+      continue;
+    }
+    if (inFence) {
+      skip[i] = true;
+      continue;
+    }
+    if (/^\s{0,3}#{1,6}\s/.test(line)) skip[i] = true;
+    // Markdown table rows (start and end with `|`) are typically targets,
+    // specs, or reference lookups, not narrative prose. Skip to keep the
+    // pattern bank focused on the prose surface where embellishment lives.
+    if (/^\s*\|.*\|\s*$/.test(line)) skip[i] = true;
+  }
+  void frontmatterClosed;
+  return skip;
+}
+
+function hasCitationNearby(lines, idx) {
+  const lo = Math.max(0, idx - 2);
+  const hi = Math.min(lines.length, idx + 3);
+  for (let i = lo; i < hi; i++) {
+    if (/\[source:|\bhttps?:\/\/|\[\^\d+\]/i.test(lines[i])) return true;
+  }
+  return false;
+}
+
+function checkArtifactBanned(content, rel) {
+  if (!isArtifactPath(rel)) return [];
+  const lines = content.split('\n');
+  const skip = buildSkipMap(lines);
+  const violations = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (skip[i]) continue;
+    if (lines[i].includes('construct-lint-ignore')) continue;
+    for (const entry of BANNED_ARTIFACT) {
+      if (entry.pattern.test(lines[i])) {
+        if (entry.requireCitation && hasCitationNearby(lines, i)) continue;
+        violations.push({ line: i + 1, label: entry.label, kind: 'artifact' });
+      }
+    }
+  }
+  return violations;
+}
+
 function checkBanned(content, filePath) {
   if (isBannedCheckSkipped(filePath)) return [];
 
@@ -180,6 +301,19 @@ export function lintFile(filePath, { rootDir = process.cwd(), fix = false } = {}
   const banned = checkBanned(content, filePath);
   for (const w of banned) warnings.push(w);
 
+  // Artifact-prose lint applies to markdown files under intake-fed artifact
+  // paths (PRD, ADR, RFC, research, knowledge, handoffs). Severity is governed
+  // by CONSTRUCT_ARTIFACT_LINT_MODE: 'block' (CLI / release-gate) routes hits
+  // to errors[]; 'warn' (PostToolUse hook default) routes to warnings[] with
+  // kind:'artifact' so the hook can let the edit through while still surfacing
+  // the finding.
+  const artifactHits = checkArtifactBanned(content, rel);
+  if (artifactHits.length > 0) {
+    const mode = process.env.CONSTRUCT_ARTIFACT_LINT_MODE || 'warn';
+    const bucket = mode === 'block' ? errors : warnings;
+    for (const v of artifactHits) bucket.push(v);
+  }
+
   return { path: rel, errors, warnings };
 }