@geraldmaron/construct 1.0.3 → 1.0.5

package/lib/embed/workspaces.mjs

@@ -2,41 +2,61 @@
  * lib/embed/workspaces.mjs — Multi-PM workspace management.
  *
  * Workspaces isolate PM workstreams while enabling cross-workspace visibility.
- * Each workspace has an owner (PM), assigned customers, and product areas.
+ * Each workspace has an owner (PM), assigned customers, product areas, and a type.
+ *
+ * Workspace types: 'product' | 'platform' | 'enterprise' | 'growth' | 'ai-product'
+ * Default type: 'product'
  *
  * Storage:
- *   ~/.cx/product-intel/workspaces/<workspace-id>.json
- *   ~/.cx/product-intel/workspaces/index.json — quick lookup
+ *   ~/.cx/knowledge/internal/workspaces/<workspace-id>.json
+ *   ~/.cx/knowledge/internal/workspaces/index.json — quick lookup
  *
  * Intake packets are routed to workspaces based on customer assignment
  * or product area matching. Cross-workspace signals trigger notifications.
  */
 
-import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync } from 'node:fs';
+import { existsSync, readFileSync, writeFileSync, mkdirSync, readdirSync, renameSync } from 'node:fs';
 import { join } from 'node:path';
 import { randomUUID } from 'node:crypto';
-import { homedir } from 'node:os';
+import { cxDir } from '../paths.mjs';
+import { knowledgeInternalStore } from '../knowledge/layout.mjs';
+
+function migrateLegacyDir(modernDir, legacyDir) {
+  if (existsSync(modernDir) || !existsSync(legacyDir)) return;
+  mkdirSync(join(modernDir, '..'), { recursive: true });
+  try { renameSync(legacyDir, modernDir); } catch { /* compatibility-only */ }
+}
 
-const WORKSPACES_DIR = join(homedir(), '.cx', 'product-intel', 'workspaces');
-const INDEX_FILE = join(WORKSPACES_DIR, 'index.json');
+function workspacePaths({ migrate = false } = {}) {
+  const modernDir = join(cxDir(), knowledgeInternalStore('workspaces'));
+  const legacyDir = join(cxDir(), 'product-intel', 'workspaces');
+  if (migrate) migrateLegacyDir(modernDir, legacyDir);
+  const workspacesDir = existsSync(modernDir) || !existsSync(legacyDir) ? modernDir : legacyDir;
+  return {
+    workspacesDir,
+    indexFile: join(workspacesDir, 'index.json'),
+  };
+}
 
 /**
  * Ensure workspaces directory exists.
  */
 function ensureDir() {
-  if (!existsSync(WORKSPACES_DIR)) {
-    mkdirSync(WORKSPACES_DIR, { recursive: true });
+  const { workspacesDir } = workspacePaths({ migrate: true });
+  if (!existsSync(workspacesDir)) {
+    mkdirSync(workspacesDir, { recursive: true });
   }
 }
 
 /**
  * Read the index file.
- * @returns {{ [key: string]: { id: string, name: string, owner: string, status: string } }}
+ * @returns {{ [key: string]: { id: string, name: string, owner: string, status: string, type: string } }}
  */
 function readIndex() {
-  if (!existsSync(INDEX_FILE)) return {};
+  const { indexFile } = workspacePaths();
+  if (!existsSync(indexFile)) return {};
   try {
-    return JSON.parse(readFileSync(INDEX_FILE, 'utf8'));
+    return JSON.parse(readFileSync(indexFile, 'utf8'));
   } catch (err) {
     process.stderr.write('[workspaces.mjs] readIndex: ' + (err?.message ?? String(err)) + '\n');
     return {};
@@ -48,10 +68,13 @@ function readIndex() {
  * @param {object} index
  */
 function writeIndex(index) {
+  const { indexFile } = workspacePaths();
   ensureDir();
-  writeFileSync(INDEX_FILE, JSON.stringify(index, null, 2) + '\n');
+  writeFileSync(indexFile, JSON.stringify(index, null, 2) + '\n');
 }
 
+const VALID_WORKSPACE_TYPES = ['product', 'platform', 'enterprise', 'growth', 'ai-product'];
+
 /**
  * Create a new workspace.
  *
@@ -61,15 +84,19 @@ function writeIndex(index) {
  * @param {string} [opts.description] - Workspace description
  * @param {string[]} [opts.productAreas] - Product areas this workspace covers
  * @param {string[]} [opts.customerIds] - Customer IDs assigned to this workspace
+ * @param {string} [opts.type] - Workspace type: 'product' | 'platform' | 'enterprise' | 'growth' | 'ai-product' (default: 'product')
  * @returns {{ id: string, workspace: Workspace }}
  */
-export function createWorkspace({ name, owner, description, productAreas = [], customerIds = [] }) {
+export function createWorkspace({ name, owner, description, productAreas = [], customerIds = [], type = 'product' }) {
   if (!name || typeof name !== 'string' || !name.trim()) {
     throw new Error('name is required');
   }
   if (!owner || typeof owner !== 'string' || !owner.trim()) {
     throw new Error('owner is required');
   }
+  if (!VALID_WORKSPACE_TYPES.includes(type)) {
+    throw new Error(`type must be one of: ${VALID_WORKSPACE_TYPES.join(', ')}`);
+  }
 
   ensureDir();
 
@@ -79,6 +106,7 @@ export function createWorkspace({ name, owner, description, productAreas = [], c
     name: name.trim(),
     owner,
     description: description || '',
+    type,
     productAreas,
     customerIds,
     status: 'active',
@@ -86,7 +114,7 @@ export function createWorkspace({ name, owner, description, productAreas = [], c
     updatedAt: new Date().toISOString(),
   };
 
-  const filePath = join(WORKSPACES_DIR, `${id}.json`);
+  const filePath = join(workspacePaths().workspacesDir, `${id}.json`);
   writeFileSync(filePath, JSON.stringify(workspace, null, 2) + '\n');
 
   // Update index
@@ -96,6 +124,7 @@ export function createWorkspace({ name, owner, description, productAreas = [], c
     name: workspace.name,
     owner: workspace.owner,
     status: workspace.status,
+    type: workspace.type,
   };
   writeIndex(index);
 
@@ -110,7 +139,7 @@ export function createWorkspace({ name, owner, description, productAreas = [], c
 export function getWorkspace(workspaceId) {
   ensureDir();
 
-  const filePath = join(WORKSPACES_DIR, `${workspaceId}.json`);
+  const filePath = join(workspacePaths().workspacesDir, `${workspaceId}.json`);
   if (!existsSync(filePath)) return null;
 
   try {
@@ -156,6 +185,7 @@ export function listWorkspaces(opts = {}) {
  * @param {string[]} [updates.productAreas]
  * @param {string[]} [updates.customerIds]
  * @param {string} [updates.status]
+ * @param {string} [updates.type] - 'product' | 'platform' | 'enterprise' | 'growth' | 'ai-product'
  * @returns {{ success: boolean, updatedAt: string }}
  */
 export function updateWorkspace(workspaceId, updates) {
@@ -164,13 +194,17 @@ export function updateWorkspace(workspaceId, updates) {
     throw new Error(`Workspace not found: ${workspaceId}`);
   }
 
+  if (updates.type !== undefined && !VALID_WORKSPACE_TYPES.includes(updates.type)) {
+    throw new Error(`type must be one of: ${VALID_WORKSPACE_TYPES.join(', ')}`);
+  }
+
   const updated = {
     ...workspace,
     ...updates,
     updatedAt: new Date().toISOString(),
   };
 
-  const filePath = join(WORKSPACES_DIR, `${workspaceId}.json`);
+  const filePath = join(workspacePaths().workspacesDir, `${workspaceId}.json`);
   writeFileSync(filePath, JSON.stringify(updated, null, 2) + '\n');
 
   // Update index
@@ -181,6 +215,7 @@ export function updateWorkspace(workspaceId, updates) {
       name: updated.name,
       owner: updated.owner,
       status: updated.status,
+      type: updated.type ?? workspace.type ?? 'product',
     };
     writeIndex(index);
   }
@@ -194,7 +229,7 @@ export function updateWorkspace(workspaceId, updates) {
  * @returns {{ success: boolean }}
  */
 export function deleteWorkspace(workspaceId) {
-  const filePath = join(WORKSPACES_DIR, `${workspaceId}.json`);
+  const filePath = join(workspacePaths().workspacesDir, `${workspaceId}.json`);
   if (!existsSync(filePath)) {
     throw new Error(`Workspace not found: ${workspaceId}`);
   }

package/lib/flavors/loader.mjs

@@ -0,0 +1,136 @@
+/**
+ * lib/flavors/loader.mjs — Role flavor overlay loader and validator.
+ *
+ * Reads frontmatter from skills/roles/<role>.<flavor>.md files, exposes:
+ *   - listFlavors(role?, profile?) — overlays that apply to role and profile
+ *   - validateFlavor(path) — frontmatter conformance check against the schema
+ *   - perRoleFlavorCount(profile) — flavor counts per role for cap enforcement
+ *
+ * The cap is enforced at sync time and in lint-prose's sibling lint-flavors.
+ * Six flavors per role per profile is the current ceiling; bumping requires
+ * an ADR. Existing roles like qa already have 6, so the cap is set tight.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = path.resolve(MODULE_DIR, '..', '..');
+const FLAVORS_DIR = path.join(REPO_ROOT, 'skills', 'roles');
+
+export const FLAVOR_CAP_PER_ROLE_PER_PROFILE = 6;
+
+// Files may start with an HTML comment block before the YAML frontmatter.
+// The /m flag lets ^ match line-start so we find the YAML wherever it sits.
+const FRONTMATTER_RE = /^---\n([\s\S]*?)\n---/m;
+
+function parseFrontmatter(content) {
+  const m = FRONTMATTER_RE.exec(content);
+  if (!m) return null;
+  const out = {};
+  let currentArrayKey = null;
+  for (const rawLine of m[1].split('\n')) {
+    const line = rawLine.replace(/\r$/, '');
+    if (!line.trim()) continue;
+    if (currentArrayKey && /^\s*-\s+/.test(line)) {
+      out[currentArrayKey].push(line.replace(/^\s*-\s+/, '').trim());
+      continue;
+    }
+    currentArrayKey = null;
+    const kv = /^([a-z_]+):\s*(.*)$/.exec(line);
+    if (!kv) continue;
+    const [, key, valueRaw] = kv;
+    const value = valueRaw.trim();
+    if (value === '') {
+      out[key] = [];
+      currentArrayKey = key;
+    } else if (value.startsWith('[') && value.endsWith(']')) {
+      const items = value.slice(1, -1).split(',').map((s) => s.trim()).filter(Boolean);
+      out[key] = items;
+    } else if (value === 'null') {
+      out[key] = null;
+    } else if (/^-?\d+$/.test(value)) {
+      out[key] = Number(value);
+    } else {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+/**
+ * Read and parse every overlay in skills/roles/. Returns { path, frontmatter }
+ * tuples. Files without parseable frontmatter are skipped silently.
+ */
+export function listAllFlavors() {
+  if (!fs.existsSync(FLAVORS_DIR)) return [];
+  const out = [];
+  for (const f of fs.readdirSync(FLAVORS_DIR)) {
+    if (!f.endsWith('.md') || f === 'README.md') continue;
+    const full = path.join(FLAVORS_DIR, f);
+    const content = fs.readFileSync(full, 'utf8');
+    const fm = parseFrontmatter(content);
+    if (fm) out.push({ path: full, file: f, frontmatter: fm });
+  }
+  return out;
+}
+
+/**
+ * Return overlays that match the given role (any-flavor for that role) and
+ * apply to the given profile. Pass undefined for either to skip that filter.
+ */
+export function listFlavors({ role, profile } = {}) {
+  return listAllFlavors().filter(({ frontmatter }) => {
+    if (role) {
+      const roleId = frontmatter.role || '';
+      const baseRole = roleId.split('.')[0];
+      if (baseRole !== role && roleId !== role) return false;
+    }
+    if (profile) {
+      const profiles = frontmatter.profiles;
+      if (!Array.isArray(profiles) || profiles.length === 0) return true;
+      if (!profiles.includes(profile)) return false;
+    }
+    return true;
+  });
+}
+
+/**
+ * Count flavor overlays per base role for a given profile.
+ * Returns { [baseRole]: count }. Excludes the canonical base file (e.g.
+ * architect.md) so only true flavors count toward the cap.
+ */
+export function perRoleFlavorCount(profile = 'rnd') {
+  const counts = {};
+  for (const entry of listFlavors({ profile })) {
+    const roleId = entry.frontmatter.role || '';
+    const isFlavor = roleId.includes('.');
+    if (!isFlavor) continue;
+    const base = roleId.split('.')[0];
+    counts[base] = (counts[base] || 0) + 1;
+  }
+  return counts;
+}
+
+/**
+ * Validate one overlay's frontmatter against the schema invariants. Returns
+ * an array of error strings; empty array means valid.
+ */
+export function validateFlavor(filePath) {
+  const errors = [];
+  if (!fs.existsSync(filePath)) return [`file not found: ${filePath}`];
+  const content = fs.readFileSync(filePath, 'utf8');
+  const fm = parseFrontmatter(content);
+  if (!fm) return [`${filePath}: missing or unparseable frontmatter`];
+
+  if (!fm.role || !/^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)?$/.test(fm.role)) {
+    errors.push(`${filePath}: invalid role "${fm.role}"`);
+  }
+  if (!Array.isArray(fm.applies_to) || fm.applies_to.length === 0) {
+    errors.push(`${filePath}: applies_to must be a non-empty array`);
+  }
+  if (!Array.isArray(fm.profiles) || fm.profiles.length === 0) {
+    errors.push(`${filePath}: profiles must be a non-empty array (run scripts/migrate-flavors.mjs)`);
+  }
+  return errors;
+}

package/lib/gates-audit.mjs

@@ -42,7 +42,7 @@ const GATE_DEFINITIONS = [
   { ciJob: 'secret scanning',                prePushLabel: null,  preCommitCheck: 'ECC secret scan',               critical: true, note: 'pre-commit ECC scan covers a subset of gitleaks rules' },
   { ciJob: 'postgres + pgvector integration', prePushLabel: null, preCommitCheck: null,                            critical: false, note: 'CI-only: requires Docker Postgres + pgvector container; not practical locally', localMirror: 'ci-only' },
   { ciJob: 'docs drift check',               prePushLabel: 'docs', critical: true },
-  { ciJob: 'comment policy',                 prePushLabel: null,  preCommitCheck: 'Construct comment-lint (staged)', critical: true, note: 'pre-commit Construct policy section calls `lint:comments --staged`' },
+  { ciJob: 'comment policy',                 prePushLabel: null,  preCommitCheck: 'Construct comment-lint', critical: true, note: 'pre-commit Construct policy section calls `lint:comments` across the full worktree' },
   { ciJob: 'template policy',                prePushLabel: null,  preCommitGhPrIntercept: true,                    critical: true, note: 'pre-push-gate intercepts `gh pr create` / `gh pr edit` and lints the body' },
 ];
 
@@ -68,8 +68,8 @@ function parsePreCommitChecks(rootDir) {
   const src = readFileSync(path, 'utf8');
   const checks = [];
   if (src.includes('scan_added_lines')) checks.push('ECC secret scan');
-  if (src.includes('construct lint:comments --staged')) checks.push('Construct comment-lint (staged)');
-  if (src.includes('construct docs:verify --staged')) checks.push('Construct docs:verify (staged)');
+  if (src.includes('construct lint:comments')) checks.push('Construct comment-lint');
+  if (src.includes('construct docs:verify')) checks.push('Construct docs:verify');
   if (src.includes('BEADS INTEGRATION')) checks.push('BEADS dispatcher');
   return checks;
 }

package/lib/health-check.mjs

@@ -67,7 +67,7 @@ export async function checkPrerequisites(options = {}) {
     required: true,
     installed: hasDocker,
     version: dockerVersion,
-    why: 'Required for telemetry backend (trace observability) and managed Postgres',
+    why: 'Required for managed Postgres; trace capture works locally without Docker',
     install: isWindows 
       ? 'https://docs.docker.com/desktop/install/windows-install/'
       : 'https://docs.docker.com/get-docker/',

package/lib/hooks/agent-tracker.mjs

@@ -119,7 +119,7 @@ try {
     if (success !== null) {
       const learningDir = join(cxDir, 'learning', agentName);
       mkdirSync(learningDir, { recursive: true });
-      
+
       const learningFile = join(learningDir, `${Date.now()}-${success ? 'success' : 'failure'}.json`);
       const learningEntry = {
         agent: agentName,
@@ -127,13 +127,32 @@ try {
         description,
         outcome,
         timestamp: new Date().toISOString(),
-        // Extract potential patterns from description
         keywords: extractKeywords(description),
         taskType: classifyTaskType(description)
       };
-      
+
       writeFileSync(learningFile, JSON.stringify(learningEntry, null, 2) + '\n');
     }
+
+    // A3 outcome capture: record the per-project outcome JSONL that feeds
+    // .cx/outcomes/_summary.json and the classifier's tiebreaker. Best-effort;
+    // any failure leaves the existing telemetry paths above untouched.
+    if (success !== null) {
+      try {
+        const { recordOutcome } = await import('../outcomes/record.mjs');
+        const { resolveActiveProfile } = await import('../profiles/loader.mjs');
+        const roleId = agentName.replace(/^cx-/, '');
+        const projectCwd = input?.cwd || process.cwd();
+        const activeProfile = resolveActiveProfile(projectCwd);
+        recordOutcome(projectCwd, {
+          role: roleId,
+          success,
+          notes: outcome,
+          source: 'agent-tracker',
+          profile: activeProfile?.id ?? null,
+        });
+      } catch { /* best effort */ }
+    }
   }
   
 } catch (error) {

package/lib/hooks/pre-compact.mjs

@@ -11,10 +11,13 @@ import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
 import { writeContextState } from '../context-state.mjs';
+import { flushReadTrackerDeltas } from '../read-tracker-store.mjs';
 
 let input = {};
 try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
 
+try { flushReadTrackerDeltas({ env: process.env }); } catch { /* best effort */ }
+
 const cwd = input?.cwd || process.cwd();
 const transcriptPath = input?.transcript_path || '';
 

package/lib/hooks/pre-push-gate.mjs

@@ -189,13 +189,26 @@ function runNpmGate(projectDir) {
   const jobs = [];
   if (hasTest || hasCi) jobs.push({ label: 'tests', cmd: runner, args: ['run', testScript],                  timeout: 90_000 });
   if (hasBuild)         jobs.push({ label: 'build', cmd: runner, args: ['run', 'build'],                     timeout: 120_000 });
-  jobs.push({                       label: 'audit', cmd: 'npm',  args: ['audit', '--omit=dev', '--audit-level=high'], timeout: 30_000 });
+  // Use the project's package manager for audit so the lockfile format matches.
+  const auditArgs = runner === 'pnpm'
+    ? ['audit', '--prod', '--audit-level=high']
+    : runner === 'yarn'
+      ? ['npm-audit', '--groups', 'dependencies', '--level', 'high']
+      : ['audit', '--omit=dev', '--audit-level=high'];
+  jobs.push({                       label: 'audit', cmd: runner, args: auditArgs, timeout: 30_000 });
 
   if (existsSync(join(projectDir, 'bin/construct'))) {
     jobs.push({ label: 'evals', cmd: 'node', args: ['bin/construct', 'evals', 'retrieval'], timeout: 60_000 });
     jobs.push({ label: 'docs',  cmd: 'node', args: ['bin/construct', 'docs:verify'],        timeout: 15_000 });
   }
 
+  if (existsSync(join(projectDir, 'scripts/lint-prose.mjs'))) {
+    jobs.push({ label: 'prose',    cmd: 'node', args: ['scripts/lint-prose.mjs'],         timeout: 15_000 });
+  }
+  if (existsSync(join(projectDir, 'scripts/lint-profiles.mjs'))) {
+    jobs.push({ label: 'profiles', cmd: 'node', args: ['scripts/lint-profiles.mjs', '--quiet'], timeout: 15_000 });
+  }
+
   return { projectDir, jobs };
 }
 

package/lib/hooks/read-tracker.mjs

@@ -7,63 +7,14 @@
  * @p95ms 10
  * @maxBlockingScope none (PostToolUse, non-blocking)
  */
-import { readFileSync, writeFileSync, mkdirSync, existsSync, appendFileSync } from 'fs';
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
 import { createHash } from 'crypto';
 import { join, resolve } from 'path';
 import { homedir } from 'os';
+import { flushReadTrackerDeltas, recordReadDelta } from '../read-tracker-store.mjs';
 
 const CX_DIR = join(homedir(), '.cx');
 const HASH_STORE = join(CX_DIR, 'file-hashes.json');
-const EFFICIENCY_STORE = join(CX_DIR, 'session-efficiency.json');
-const WARN_FLAGS = join(CX_DIR, 'warn-flags.txt');
-const SESSION_IDLE_RESET_MS = 2 * 60 * 60 * 1000;
-const REPEATED_READ_WARNING_THRESHOLD = 5;
-const REPEATED_READ_TIER2_THRESHOLD = 8;
-const LARGE_READ_WARNING_THRESHOLD = 3;
-const TOTAL_BYTES_WARNING_THRESHOLD = 750_000;
-
-// Bound per-session `stats.files` so the read-tracking map cannot grow
-// without limit across long sessions. The hook is a fresh node process per
-// Read, so every invocation must read-mutate-write the full state — there
-// is no in-memory accumulator that would survive between calls. The LRU cap
-// drops the oldest entries by `lastReadAt`.
-
-const FILES_LRU_CAP = 200;
-
-function loadEfficiencyStats(nowIso) {
-  const fresh = {
-    sessionStartedAt: nowIso,
-    lastUpdatedAt: nowIso,
-    readCount: 0,
-    uniqueFileCount: 0,
-    repeatedReadCount: 0,
-    largeReadCount: 0,
-    totalBytesRead: 0,
-    warnings: {},
-    files: {},
-  };
-
-  try {
-    const existing = JSON.parse(readFileSync(EFFICIENCY_STORE, 'utf8'));
-    const lastUpdated = new Date(existing.lastUpdatedAt || 0).getTime();
-    if (!lastUpdated || Date.now() - lastUpdated > SESSION_IDLE_RESET_MS) return fresh;
-    return { ...fresh, ...existing, warnings: existing.warnings || {}, files: existing.files || {} };
-  } catch {
-    return fresh;
-  }
-}
-
-function appendWarning(message) {
-  try { appendFileSync(WARN_FLAGS, `${message}\n`); } catch { /* best effort */ }
-}
-
-function topRepeatedPath(files) {
-  return Object.entries(files || {})
-    .map(([filePath, value]) => ({ filePath, count: Number(value?.count || 0) }))
-    .filter((entry) => entry.count > 1)
-    .sort((a, b) => b.count - a.count || a.filePath.localeCompare(b.filePath))[0];
-}
-
 let input = {};
 try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
 
@@ -81,7 +32,6 @@ try {
   const nowIso = new Date().toISOString();
   const requestedLimit = Number(input?.tool_input?.limit || 0);
   const effectiveLimit = requestedLimit > 0 ? requestedLimit : 2000;
-  const isLargeRead = effectiveLimit > 400;
 
   mkdirSync(CX_DIR, { recursive: true });
   let store = {};
@@ -95,58 +45,17 @@ try {
     if (new Date(v.ts).getTime() < cutoff) delete store[k];
   }
 
-  const stats = loadEfficiencyStats(nowIso);
-  const existingFile = stats.files[absPath];
-  stats.readCount += 1;
-  stats.totalBytesRead += content.length;
-  if (isLargeRead) stats.largeReadCount += 1;
-  if (existingFile) {
-    stats.repeatedReadCount += 1;
-  } else {
-    stats.uniqueFileCount += 1;
-  }
-  stats.files[absPath] = {
-    count: (existingFile?.count || 0) + 1,
+  writeFileSync(HASH_STORE, JSON.stringify(store, null, 2));
+  recordReadDelta({
+    path: absPath,
     size: content.length,
-    lastReadAt: nowIso,
-    lastRequestedLimit: effectiveLimit,
-  };
+    limit: effectiveLimit,
+    ts: nowIso,
+  }, process.env);
 
-  // LRU cap: bound stats.files to FILES_LRU_CAP entries by lastReadAt so the
-  // structure does not grow without limit across long sessions.
-  const fileEntries = Object.entries(stats.files);
-  if (fileEntries.length > FILES_LRU_CAP) {
-    fileEntries.sort((a, b) => (a[1]?.lastReadAt || '').localeCompare(b[1]?.lastReadAt || ''));
-    const drop = fileEntries.length - FILES_LRU_CAP;
-    for (let i = 0; i < drop; i++) delete stats.files[fileEntries[i][0]];
+  if (process.env.CONSTRUCT_READ_TRACKER_FLUSH === '1') {
+    flushReadTrackerDeltas({ nowIso, env: process.env });
   }
-
-  if (stats.repeatedReadCount >= REPEATED_READ_WARNING_THRESHOLD && !stats.warnings.repeatedReads) {
-    const top = topRepeatedPath(stats.files);
-    const topNote = top ? ` Top repeat: ${top.filePath} (${top.count}x).` : '';
-    appendWarning(`Efficiency: ${stats.repeatedReadCount} repeated reads this session.${topNote} Use rg or construct distill before re-reading more files.`);
-    stats.warnings.repeatedReads = nowIso;
-
-    if (stats.repeatedReadCount >= REPEATED_READ_TIER2_THRESHOLD && !stats.warnings.repeatedReadsTier2) {
-      appendWarning(`Efficiency: ${stats.repeatedReadCount} repeated reads this session — consider using construct distill or rg before re-reading entire files.`);
-      stats.warnings.repeatedReadsTier2 = nowIso;
-    }
-  }
-
-  if (stats.largeReadCount >= LARGE_READ_WARNING_THRESHOLD && !stats.warnings.largeReads) {
-    appendWarning(`Efficiency: ${stats.largeReadCount} large reads this session — prefer rg/glob plus targeted reads under 400 lines.`);
-    stats.warnings.largeReads = nowIso;
-  }
-
-  if (stats.totalBytesRead >= TOTAL_BYTES_WARNING_THRESHOLD && !stats.warnings.totalBytes) {
-    appendWarning(`Efficiency: ${Math.round(stats.totalBytesRead / 1024)} KB read this session — consider distill/query-focused retrieval or compact context before continuing.`);
-    stats.warnings.totalBytes = nowIso;
-  }
-
-  stats.lastUpdatedAt = nowIso;
-
-  writeFileSync(HASH_STORE, JSON.stringify(store, null, 2));
-  writeFileSync(EFFICIENCY_STORE, JSON.stringify(stats, null, 2));
 } catch { /* best effort */ }
 
 process.exit(0);

package/lib/hooks/session-optimize.mjs

@@ -128,8 +128,9 @@ function optimizeAgent(agentName) {
   const startTime = Date.now();
   
   try {
-    // Run construct optimize with auto-apply (no --dry-run)
-    const result = spawnSync(CONSTRUCT_BIN, ['optimize', agentName, `--days=${OPTIMIZATION_DAYS}`], {
+    // Preview only. The new contract requires an explicit --apply from the
+    // operator; hook-driven runs must never modify prompt files.
+    const result = spawnSync(CONSTRUCT_BIN, ['optimize', agentName, `--days=${OPTIMIZATION_DAYS}`, '--dry-run'], {
       cwd,
       encoding: 'utf8',
       timeout: 300000, // 5 minutes timeout for optimization

package/lib/hooks/session-reflect.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+/**
+ * lib/hooks/session-reflect.mjs — Session end auto-reflect hook.
+ *
+ * Runs as a Stop hook. Reads the transcript, extracts a deterministic session
+ * summary, and records it via the observation store so subsequent sessions
+ * can search what happened. Closes the manual-reflect gap that left learning
+ * to operator discipline.
+ *
+ * Hard 500ms wall-clock budget. Exits 0 on any failure — observation capture
+ * is best-effort by design.
+ *
+ * Opt-out: CONSTRUCT_REFLECT_AUTO=off
+ *
+ * @p95ms 300
+ * @maxBlockingScope Stop
+ */
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+const HARD_BUDGET_MS = 500;
+const startedAt = Date.now();
+
+// Opt-out before any heavy work — the env check is cheaper than parsing input.
+if (process.env.CONSTRUCT_REFLECT_AUTO === 'off') process.exit(0);
+
+let input = {};
+try { input = JSON.parse(readFileSync(0, 'utf8')); } catch { process.exit(0); }
+
+const cwd = input?.cwd || process.cwd();
+const projectName = cwd.split('/').pop() || 'project';
+
+// Only run for Construct projects — same gate as session-optimize.mjs.
+if (projectName !== 'construct' && !existsSync(join(cwd, '.cx'))) process.exit(0);
+
+const transcriptPath =
+  input?.transcript_path ||
+  input?.transcriptPath ||
+  process.env.CLAUDE_TRANSCRIPT_PATH ||
+  null;
+
+if (!transcriptPath) process.exit(0);
+
+// Wall-clock budget guard. If the extractor blows past the cap (it shouldn't
+// — it's deterministic and O(n) over transcript lines), the parent process
+// exits without writing. The next session-stop tries again.
+const deadline = setTimeout(() => process.exit(0), HARD_BUDGET_MS);
+deadline.unref();
+
+try {
+  const { runReflectAuto } = await import('../reflect.mjs');
+  const sessionId = input?.session_id || input?.sessionId || null;
+  const durationMs = input?.session_duration_ms || null;
+  await runReflectAuto({ transcriptPath, cwd, sessionId, durationMs });
+} catch {
+  // Best-effort — observation capture must not affect session exit.
+}
+
+const elapsed = Date.now() - startedAt;
+if (elapsed > HARD_BUDGET_MS) {
+  // Log only if budget exceeded — surfaces in construct doctor if it becomes
+  // a pattern. Otherwise silent.
+  try {
+    process.stderr.write(`[session-reflect] over budget: ${elapsed}ms\n`);
+  } catch { /* stderr closed — nothing to do */ }
+}
+
+process.exit(0);