@geraldmaron/construct 1.0.21 → 1.0.24

package/lib/strategy-store.mjs

@@ -6,23 +6,19 @@
  * Strategy documents are NEVER auto-updated from ingested documents — they require
  * an explicit writeStrategy() call from a privileged caller.
  *
- * In team/enterprise mode Postgres is the secondary store (best-effort). Each scope
- * is stored as a separate row whose content is prefixed with `scope:{name}\n` so we
- * can store and retrieve scopes without adding a new column to the existing schema.
+ * Construct now uses embedded LanceDB for vectors only; strategy remains
+ * filesystem-primary for simplicity and Git-backed collaboration.
  *
  * getStrategyDigest() / getStrategyDigestSync() return a compact block (≤ 500 tokens)
  * suitable for injection into agent prompts. getStrategyDigestSync() is the file-only
  * synchronous path required where await is not available (e.g. prompt assembly).
  */
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, statSync } from 'node:fs';
 import { join, basename } from 'node:path';
 import { cxDir } from './paths.mjs';
-import { hasSqlStore } from './storage/sql-store.mjs';
-import { createSqlClient } from './storage/backend.mjs';
 
 const VALID_SCOPES = ['product', 'technical', 'gtm', 'platform'];
-const SCOPE_PREFIX = 'scope:';
 
 // ── Path helpers ──────────────────────────────────────────────────────────────
 
@@ -38,9 +34,6 @@ export function strategyFilePath(scope = 'product', env = process.env) {
 
 /**
  * Return scope names that have corresponding files in the strategy directory.
- *
- * @param {object} [env]
- * @returns {string[]}
  */
 export function listStrategyScopes(env = process.env) {
   const dir = strategyDir(env);
@@ -57,315 +50,71 @@ export function listStrategyScopes(env = process.env) {
 // ── Read helpers ──────────────────────────────────────────────────────────────
 
 /**
- * Read one strategy scope from Postgres (primary) or file (fallback).
- *
- * @param {string} [scope]
- * @param {object} [env]
- * @returns {Promise<{ content: string, version: number, updatedAt: string, source: 'postgres'|'file'|'none', scope: string }>}
+ * Read one strategy scope from file.
  */
 export async function readStrategy(scope = 'product', env = process.env) {
-  if (hasSqlStore(env)) {
-    const client = createSqlClient(env);
-    try {
-      const project = env.CX_PROJECT || 'default';
-      const prefix = `${SCOPE_PREFIX}${scope}\n`;
-
-      // Rows stored with the scope prefix — match on content prefix
-      const rows = await client`
-        select content, version, updated_at
-        from construct_strategy
-        where project = ${project}
-          and content like ${prefix + '%'}
-        order by version desc
-        limit 1
-      `;
-
-      if (rows.length > 0) {
-        const row = rows[0];
-        return {
-          content: row.content.startsWith(prefix) ? row.content.slice(prefix.length) : row.content,
-          version: row.version,
-          updatedAt: row.updated_at instanceof Date ? row.updated_at.toISOString() : String(row.updated_at),
-          source: 'postgres',
-          scope,
-        };
-      }
-    } catch {
-      // Postgres unavailable — fall through to file
-    } finally {
-      if (client) await client.end({ timeout: 5 }).catch(() => {});
-    }
-  }
-
   const filePath = strategyFilePath(scope, env);
-  if (existsSync(filePath)) {
+  if (!existsSync(filePath)) {
+    return { content: '', version: 0, updatedAt: null, source: 'none', scope };
+  }
+  try {
     const content = readFileSync(filePath, 'utf8');
-    return { content, version: 1, updatedAt: new Date().toISOString(), source: 'file', scope };
+    const stat = statSync(filePath);
+    return {
+      content,
+      version: 1,
+      updatedAt: stat.mtime.toISOString(),
+      source: 'file',
+      scope,
+    };
+  } catch {
+    return { content: '', version: 0, updatedAt: null, source: 'none', scope };
   }
-
-  return { content: '', version: 0, updatedAt: new Date().toISOString(), source: 'none', scope };
 }
 
 /**
- * Read all present strategy scopes.
- *
- * When Postgres is available it reads all rows for the project and parses scope
- * from the prefix. Files are used as the fallback or supplement for scopes that
- * have no Postgres row.
- *
- * @param {object} [env]
- * @returns {Promise<Map<string, { content: string, version: number, updatedAt: string, source: string }>>}
+ * Read all strategy scopes into a Map.
  */
 export async function readAllStrategies(env = process.env) {
   const result = new Map();
-
-  if (hasSqlStore(env)) {
-    const client = createSqlClient(env);
-    try {
-      const project = env.CX_PROJECT || 'default';
-
-      // Fetch all rows — latest version per scope
-      const rows = await client`
-        select distinct on (
-          substring(content from 1 for position(E'\n' in content))
-        ) content, version, updated_at
-        from construct_strategy
-        where project = ${project}
-          and content like ${SCOPE_PREFIX + '%'}
-        order by
-          substring(content from 1 for position(E'\n' in content)),
-          version desc
-      `;
-
-      for (const row of rows) {
-        const firstNewline = row.content.indexOf('\n');
-        if (firstNewline === -1) continue;
-        const header = row.content.slice(0, firstNewline);
-        if (!header.startsWith(SCOPE_PREFIX)) continue;
-        const rowScope = header.slice(SCOPE_PREFIX.length);
-        const content = row.content.slice(firstNewline + 1);
-        result.set(rowScope, {
-          content,
-          version: row.version,
-          updatedAt: row.updated_at instanceof Date ? row.updated_at.toISOString() : String(row.updated_at),
-          source: 'postgres',
-        });
-      }
-    } catch {
-      // Fall through to file-based reads
-    } finally {
-      if (client) await client.end({ timeout: 5 }).catch(() => {});
-    }
-  }
-
-  // Supplement / replace with file-based reads for any scope present on disk
-  const fileScopes = listStrategyScopes(env);
-  for (const fileScope of fileScopes) {
-    if (result.has(fileScope)) continue;
-    const filePath = strategyFilePath(fileScope, env);
-    try {
-      const content = readFileSync(filePath, 'utf8');
-      result.set(fileScope, {
-        content,
-        version: 1,
-        updatedAt: new Date().toISOString(),
-        source: 'file',
-      });
-    } catch {
-      // Skip unreadable files
-    }
+  const scopes = listStrategyScopes(env);
+  for (const scope of scopes) {
+    const data = await readStrategy(scope, env);
+    if (data.source !== 'none') result.set(scope, data);
   }
-
   return result;
 }
 
-// ── Digest helpers ────────────────────────────────────────────────────────────
-
-/**
- * Parse markdown into sections split on ## headers.
- *
- * @param {string} content
- * @returns {Array<{ header: string, body: string }>}
- */
-function parseSections(content) {
-  const lines = content.split('\n');
-  const sections = [];
-  let current = null;
-
-  for (const line of lines) {
-    if (line.startsWith('## ')) {
-      if (current) sections.push(current);
-      current = { header: line.slice(3).trim(), body: '' };
-    } else if (current) {
-      current.body += line + '\n';
-    }
-  }
-  if (current) sections.push(current);
-  return sections;
-}
-
-/**
- * Truncate a body to the first N sentences.
- *
- * @param {string} body
- * @param {number} maxSentences
- * @returns {string}
- */
-function firstSentences(body, maxSentences = 2) {
-  const trimmed = body.trim();
-  if (!trimmed) return '';
-  const sentences = trimmed.match(/[^.!?\n]+[.!?\n]+/g) || [trimmed];
-  return sentences.slice(0, maxSentences).join(' ').trim();
-}
-
-/**
- * Build a compact markdown block from a single scope's content.
- *
- * @param {string} scopeName
- * @param {string} content
- * @param {number} charBudget — remaining character budget; mutated by reference via returned delta
- * @returns {{ text: string, charsUsed: number }}
- */
-function buildScopeBlock(scopeName, content, charBudget) {
-  const sections = parseSections(content);
-  if (!sections.length) return { text: '', charsUsed: 0 };
-
-  const lines = [`### ${scopeName}`];
-  let used = scopeName.length + 5;
-
-  for (const { header, body } of sections) {
-    if (used >= charBudget) break;
-    const excerpt = firstSentences(body, 2);
-    const line = excerpt ? `**${header}:** ${excerpt}` : `**${header}**`;
-    lines.push(line);
-    used += line.length + 1;
-  }
-
-  const text = lines.join('\n');
-  return { text, charsUsed: used };
-}
-
 /**
- * Return a compact strategy digest (≤ 500 tokens) for agent prompt injection.
- *
- * Reads all present scopes asynchronously. Returns empty string when no scopes exist.
- *
- * @param {object} [env]
- * @returns {Promise<string>}
+ * Synchronous digest for prompt assembly.
  */
-export async function getStrategyDigest(env = process.env) {
+export function getStrategyDigestSync(scope = 'product', env = process.env) {
+  const filePath = strategyFilePath(scope, env);
+  if (!existsSync(filePath)) return '';
   try {
-    const all = await readAllStrategies(env);
-    if (!all.size) return '';
-
-    const TOKEN_LIMIT = 500;
-    let charBudget = TOKEN_LIMIT * 4;
-    const parts = ['## Active strategy'];
-
-    for (const [scopeName, { content }] of all) {
-      if (!content) continue;
-      const { text, charsUsed } = buildScopeBlock(scopeName, content, charBudget);
-      if (text) {
-        parts.push(text);
-        charBudget -= charsUsed;
-      }
-      if (charBudget <= 0) break;
-    }
-
-    return parts.length > 1 ? parts.join('\n') : '';
+    const content = readFileSync(filePath, 'utf8');
+    return content.trim().slice(0, 2000); // approx 500 tokens
   } catch {
     return '';
   }
 }
 
 /**
- * Synchronous file-only strategy digest for prompt-composer.js.
- *
- * Reads all .md files present in the strategy directory directly. Never reads
- * Postgres. Returns empty string when the directory is absent or empty.
- *
- * @param {object} [env]
- * @returns {string}
+ * Async digest for general use.
  */
-export function getStrategyDigestSync(env = process.env) {
-  try {
-    const dir = strategyDir(env);
-    if (!existsSync(dir)) return '';
-
-    const files = readdirSync(dir).filter((f) => f.endsWith('.md'));
-    if (!files.length) return '';
-
-    const TOKEN_LIMIT = 500;
-    let charBudget = TOKEN_LIMIT * 4;
-    const parts = ['## Active strategy'];
-
-    for (const file of files) {
-      if (charBudget <= 0) break;
-      const scopeName = basename(file, '.md');
-      let content;
-      try {
-        content = readFileSync(join(dir, file), 'utf8');
-      } catch {
-        continue;
-      }
-      if (!content) continue;
-      const { text, charsUsed } = buildScopeBlock(scopeName, content, charBudget);
-      if (text) {
-        parts.push(text);
-        charBudget -= charsUsed;
-      }
-    }
-
-    return parts.length > 1 ? parts.join('\n') : '';
-  } catch {
-    return '';
-  }
+export async function getStrategyDigest(scope = 'product', env = process.env) {
+  const data = await readStrategy(scope, env);
+  return data.content.trim().slice(0, 2000);
 }
 
-// ── Write ─────────────────────────────────────────────────────────────────────
+// ── Write helpers ─────────────────────────────────────────────────────────────
 
 /**
- * Write a strategy scope to file (always) and Postgres (best-effort if available).
- *
- * The scope parameter defaults to 'product'. When writing to Postgres the content
- * is prefixed with `scope:{name}\n` to allow per-scope storage without a schema change.
- *
- * @param {string} content
- * @param {string} [scope]
- * @param {object} [opts]
- * @param {string} [opts.updatedBy]
- * @param {object} [opts.env]
+ * Write a strategy scope to file.
  */
 export async function writeStrategy(content, scope = 'product', { updatedBy, env = process.env } = {}) {
   const filePath = strategyFilePath(scope, env);
   const dir = strategyDir(env);
   if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
   writeFileSync(filePath, content, 'utf8');
-
-  if (!hasSqlStore(env)) return;
-
-  const client = createSqlClient(env);
-  try {
-    const project = env.CX_PROJECT || 'default';
-    const scopedContent = `${SCOPE_PREFIX}${scope}\n${content}`;
-    const prefix = `${SCOPE_PREFIX}${scope}\n`;
-
-    const existing = await client`
-      select version from construct_strategy
-      where project = ${project}
-        and content like ${prefix + '%'}
-      order by version desc
-      limit 1
-    `;
-    const nextVersion = existing.length > 0 ? existing[0].version + 1 : 1;
-
-    await client`
-      insert into construct_strategy (project, content, version, updated_by)
-      values (${project}, ${scopedContent}, ${nextVersion}, ${updatedBy ?? null})
-    `;
-  } catch {
-    // Best-effort Postgres write — file write already succeeded
-  } finally {
-    if (client) await client.end({ timeout: 5 }).catch(() => {});
-  }
 }

package/lib/template-registry.mjs

@@ -0,0 +1,73 @@
+/**
+ * lib/template-registry.mjs — specialist → template ownership map.
+ *
+ * Single source of truth for which canonical doc templates a specialist
+ * authors. The prompt-surface test gates assert that each specialist's
+ * prompt references `get_template(<name>)` for its native artifacts (so
+ * prompts stay pointers rather than restated structure) and that every
+ * named template actually resolves on disk.
+ *
+ * Adding a new specialist or template: extend SPECIALIST_TEMPLATES, ship the
+ * template file under templates/docs/<name>.md, and wire the prompt to call
+ * `get_template("<name>")` in the output-format section.
+ *
+ * Project overrides at .cx/templates/docs/<name>.md take precedence at fetch
+ * time via the get_template MCP tool; the registry only names the canonical
+ * shipped name.
+ */
+
+export const SPECIALIST_TEMPLATES = {
+  // Tranche 1 — five new templates authored alongside this map.
+  'cx-reviewer':        ['code-review-report'],
+  'cx-security':        ['security-audit-report'],
+  'cx-qa':              ['qa-report', 'test-plan'],
+  'cx-debugger':        ['debug-investigation'],
+  'cx-devil-advocate':  ['verdict'],
+  'cx-evaluator':       ['verdict'],
+  'cx-trace-reviewer':  ['verdict'],
+  'cx-explorer':        ['verdict'],
+  'cx-legal-compliance':['verdict'],
+
+  // Already-wired specialists pinned here so the gate guards them against drift.
+  'cx-architect':       ['adr', 'rfc', 'architecture-review'],
+  'cx-researcher':      ['research-brief', 'evidence-brief'],
+  'cx-sre':             ['runbook', 'incident-report'],
+  'cx-product-manager': ['prd', 'meta-prd'],
+
+  // Tranche 2 — three lower-frequency artifacts.
+  'cx-accessibility':   ['accessibility-audit'],
+};
+
+// The orchestrator owns the task-packet shape and emits it at dispatch time
+// rather than authoring it as a doc. Pinned here so the existence gate
+// and reverse-coverage gate both pass without conflating dispatch with
+// authoring.
+
+export const SHARED_TEMPLATES = new Set([
+  'task-packet',
+]);
+
+// Roles whose prompts may legitimately reference templates not in the map
+// (e.g. cx-docs-keeper authors many doc types via a listing tool, not a
+// single owned template). Entries here opt out of the reverse-coverage gate,
+// not the per-mapping gate above.
+
+export const TEMPLATE_OWNERSHIP_EXEMPTIONS = new Set([
+  'construct_guide',
+  'onboarding',
+  'memo',
+  'skill-artifact',
+  'persona-artifact',
+  'customer-profile',
+  'one-pager',
+  'strategy',
+  'backlog-proposal',
+  'changelog-entry',
+  'prfaq',
+  'signal-brief',
+  'research-finding',
+  'product-intelligence-report',
+  'rfc-platform',
+  'prd-platform',
+  'prd-business',
+]);

package/lib/term-format.mjs

@@ -0,0 +1,75 @@
+/**
+ * lib/term-format.mjs — single source of truth for human-facing terminal presentation.
+ *
+ * Centralizes terminal color enable/disable and width so accessibility behavior
+ * (NO_COLOR, non-TTY pipes, TERM=dumb, narrow terminals) is decided in one tested place
+ * instead of being re-implemented per call site. Presentation only: this module never
+ * touches machine-readable output (`--json`, parsed hook tokens, registries, contracts) —
+ * callers keep those paths away from here. See rules/common/neurodivergent-output.md.
+ */
+
+const ESC = "[";
+
+const CODES = { bold: "1", dim: "2", reset: "0", red: "31", green: "32", yellow: "33", cyan: "36" };
+
+const PALETTE_KEYS = Object.keys(CODES);
+
+const EMPTY_PALETTE = Object.freeze(Object.fromEntries(PALETTE_KEYS.map((k) => [k, ""])));
+
+// Color is opt-in by the caller AND gated on an interactive, color-capable stream. Any
+// NO_COLOR value and TERM=dumb force plain text; a non-TTY stream (pipe, file, CI) does too.
+
+export function shouldUseColor({ enabled = true, stream = process.stdout, env = process.env } = {}) {
+  return Boolean(enabled) && Boolean(stream && stream.isTTY) && !env.NO_COLOR && env.TERM !== "dumb";
+}
+
+// A palette is the full key set whether or not color is on, so callers can interpolate
+// every field unconditionally; when color is off each field is the empty string.
+
+export function palette(useColor) {
+  if (!useColor) return EMPTY_PALETTE;
+  return Object.fromEntries(PALETTE_KEYS.map((k) => [k, `${ESC}${CODES[k]}m`]));
+}
+
+export function resolveColors(opts = {}) {
+  return palette(shouldUseColor(opts));
+}
+
+// Wrapping width for human prose. Falls back to 80 when the stream width is unknown
+// (non-TTY, redirected) and caps wide terminals so lines stay scannable rather than long.
+
+export function termWidth(stream = process.stdout, { fallback = 80, max = 100 } = {}) {
+  const cols = stream && Number.isInteger(stream.columns) ? stream.columns : fallback;
+  return Math.min(cols, max);
+}
+
+// Word-wrap one paragraph to width. Existing newlines stay as hard breaks; a single word
+// longer than width is never split — it sits on its own line and overflows rather than
+// becoming two unreadable fragments.
+
+export function wrapText(text, width = termWidth()) {
+  const out = [];
+  for (const hardLine of String(text).split("\n")) {
+    if (hardLine === "") {
+      out.push("");
+      continue;
+    }
+    let line = "";
+    for (const word of hardLine.split(/\s+/)) {
+      if (line === "") {
+        line = word;
+      } else if (line.length + 1 + word.length <= width) {
+        line += ` ${word}`;
+      } else {
+        out.push(line);
+        line = word;
+      }
+    }
+    out.push(line);
+  }
+  return out.join("\n");
+}
+
+export function stripAnsi(text) {
+  return String(text).replace(/\[[0-9;]*m/g, "");
+}