chati-dev 3.3.1 → 4.0.0

package/src/orchestrator/pipeline-manager.js

@@ -5,9 +5,10 @@
 
 import { AGENT_PIPELINE, getNextAgent } from './agent-selector.js';
 import { calculateBracket, estimateRemaining } from '../context/bracket-tracker.js';
-import { track as telemetryTrack, flush as telemetryFlush } from '../telemetry/collector.js';
+import { initCollector, track as telemetryTrack, flush as telemetryFlush } from '../telemetry/collector.js';
 import { sendEvents } from '../telemetry/sender.js';
-import { getTelemetryConfig } from '../telemetry/config.js';
+import { getTelemetryConfig, isEnabled as isTelemetryEnabled } from '../telemetry/config.js';
+import { getCurrentVersion } from '../upgrade/checker.js';
 
 /**
  * Pipeline phases in order.
@@ -39,7 +40,7 @@ const QA_IMPLEMENTATION_THRESHOLD = 95;
  * @returns {object} Pipeline state
  */
 export function initPipeline(options = {}) {
-  const { isGreenfield = true, mode = 'discover' } = options;
+  const { isGreenfield = true, mode = 'discover', targetDir } = options;
 
   const agents = {};
   for (const agentDef of AGENT_PIPELINE) {
@@ -61,9 +62,25 @@ export function initPipeline(options = {}) {
     };
   }
 
+  const resolvedDir = targetDir || process.cwd();
+
+  // Initialize telemetry collector based on project config
+  initCollector(isTelemetryEnabled(resolvedDir));
+
+  const sessionId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+  telemetryTrack('session_started', {
+    sessionId,
+    pipelineType: 'full',
+    mode,
+  });
+
   return {
     phase: mode,
     isGreenfield,
+    sessionId,
+    targetDir: resolvedDir,
+    chatiVersion: getCurrentVersion(resolvedDir) || 'unknown',
     startedAt: new Date().toISOString(),
     completedAt: null,
     agents,
@@ -96,7 +113,7 @@ const QUICK_FLOW_AGENTS = ['brief', 'dev', 'qa-implementation', 'devops'];
  * @returns {object} Pipeline state
  */
 export function initQuickFlowPipeline(options = {}) {
-  const { isGreenfield = false, mode = 'discover' } = options;
+  const { isGreenfield = false, mode = 'discover', targetDir } = options;
 
   const agents = {};
   for (const agentName of QUICK_FLOW_AGENTS) {
@@ -108,10 +125,26 @@ export function initQuickFlowPipeline(options = {}) {
     };
   }
 
+  const resolvedDir = targetDir || process.cwd();
+
+  // Initialize telemetry collector based on project config
+  initCollector(isTelemetryEnabled(resolvedDir));
+
+  const sessionId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+  telemetryTrack('session_started', {
+    sessionId,
+    pipelineType: 'quick-flow',
+    mode,
+  });
+
   return {
     phase: mode,
     isGreenfield,
     isQuickFlow: true,
+    sessionId,
+    targetDir: resolvedDir,
+    chatiVersion: getCurrentVersion(resolvedDir) || 'unknown',
     startedAt: new Date().toISOString(),
     completedAt: null,
     agents,
@@ -130,7 +163,7 @@ export function initQuickFlowPipeline(options = {}) {
  * @returns {object} Pipeline state
  */
 export function initStandardFlowPipeline(options = {}) {
-  const { isGreenfield = false, mode = 'discover' } = options;
+  const { isGreenfield = false, mode = 'discover', targetDir } = options;
 
   const agents = {};
   for (const agentName of STANDARD_FLOW_AGENTS) {
@@ -142,10 +175,26 @@ export function initStandardFlowPipeline(options = {}) {
     };
   }
 
+  const resolvedDir = targetDir || process.cwd();
+
+  // Initialize telemetry collector based on project config
+  initCollector(isTelemetryEnabled(resolvedDir));
+
+  const sessionId = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+  telemetryTrack('session_started', {
+    sessionId,
+    pipelineType: 'standard',
+    mode,
+  });
+
   return {
     phase: mode,
     isGreenfield,
     isStandardFlow: true,
+    sessionId,
+    targetDir: resolvedDir,
+    chatiVersion: getCurrentVersion(resolvedDir) || 'unknown',
     startedAt: new Date().toISOString(),
     completedAt: null,
     agents,
@@ -245,13 +294,24 @@ export function advancePipeline(pipelineState, completedAgent, results = {}) {
 
       // Pipeline complete
       newState.completedAt = new Date().toISOString();
+      const pipelineType1 = newState.isQuickFlow ? 'quick-flow' : newState.isStandardFlow ? 'standard' : 'full';
+      const totalDuration1 = Date.now() - new Date(newState.startedAt).getTime();
       telemetryTrack('pipeline_completed', {
-        pipelineType: newState.isQuickFlow ? 'quick-flow' : newState.isStandardFlow ? 'standard' : 'full',
-        totalDuration: Date.now() - new Date(newState.startedAt).getTime(),
+        pipelineType: pipelineType1,
+        totalDuration: totalDuration1,
         agentsRun: newState.completedAgents.length,
         finalStatus: 'completed',
         deviationCount: (newState.modeTransitions || []).length,
       });
+      telemetryTrack('session_completed', {
+        sessionId: newState.sessionId || 'unknown',
+        pipelineType: pipelineType1,
+        mode: newState.phase === 'deploy' ? 'deploy' : 'build',
+        finalStage: newState.phase,
+        duration: totalDuration1,
+        agentCount: newState.completedAgents.length,
+        success: true,
+      });
       const flushedEvents = telemetryFlush();
       if (flushedEvents.length > 0) {
         const tConfig = getTelemetryConfig(newState.targetDir || process.cwd());
@@ -306,13 +366,24 @@ export function advancePipeline(pipelineState, completedAgent, results = {}) {
 
     // Pipeline complete
     newState.completedAt = new Date().toISOString();
+    const pipelineType2 = newState.isQuickFlow ? 'quick-flow' : newState.isStandardFlow ? 'standard' : 'full';
+    const totalDuration2 = Date.now() - new Date(newState.startedAt).getTime();
     telemetryTrack('pipeline_completed', {
-      pipelineType: newState.isQuickFlow ? 'quick-flow' : newState.isStandardFlow ? 'standard' : 'full',
-      totalDuration: Date.now() - new Date(newState.startedAt).getTime(),
+      pipelineType: pipelineType2,
+      totalDuration: totalDuration2,
       agentsRun: newState.completedAgents.length,
       finalStatus: 'completed',
       deviationCount: (newState.modeTransitions || []).length,
     });
+    telemetryTrack('session_completed', {
+      sessionId: newState.sessionId || 'unknown',
+      pipelineType: pipelineType2,
+      mode: newState.phase === 'deploy' ? 'deploy' : 'build',
+      finalStage: newState.phase,
+      duration: totalDuration2,
+      agentCount: newState.completedAgents.length,
+      success: true,
+    });
     const flushedEvents2 = telemetryFlush();
     if (flushedEvents2.length > 0) {
       const tConfig2 = getTelemetryConfig(newState.targetDir || process.cwd());

package/src/telemetry/config.js

@@ -24,7 +24,7 @@ export function getTelemetryConfig(targetDir) {
   const configPath = join(targetDir, 'chati.dev', 'config.yaml');
 
   const defaults = {
-    enabled: false,
+    enabled: true,
     anonymousId: null,
     endpoint: 'https://chati-telemetry.vercel.app/api/events',
     apiKey: '10b0b54ba4f392fa46379ba778062ab0af5ca61e79609a7dce4aadd660104b56',

package/src/telemetry/index.js

@@ -5,7 +5,7 @@
  * All telemetry is opt-in and anonymous.
  */
 
-export { TELEMETRY_EVENTS, validateEvent } from './schema.js';
+export { TELEMETRY_EVENTS, validateEvent, EVENT_PROPERTY_RULES } from './schema.js';
 export { getTelemetryConfig, isEnabled, setEnabled, getAnonymousId } from './config.js';
 export { initCollector, track, flush, getBufferSize, getStatus } from './collector.js';
 export { sendEvents, DEFAULT_ENDPOINT } from './sender.js';

package/src/telemetry/schema.js

@@ -1,7 +1,7 @@
 /**
  * @fileoverview Telemetry event schema and validation.
  *
- * Defines the 6 event types collected by opt-in telemetry.
+ * Defines the 9 event types collected by telemetry.
  * Zero PII — only anonymous usage metrics.
  */
 
@@ -16,6 +16,9 @@ export const TELEMETRY_EVENTS = [
   'pipeline_completed',
   'circuit_breaker_triggered',
   'error_occurred',
+  'session_started',
+  'session_completed',
+  'token_usage',
 ];
 
 // ---------------------------------------------------------------------------
@@ -44,18 +47,48 @@ const EVENT_PROPERTIES = {
   error_occurred: [
     'errorType', 'agent', 'provider', 'phase',
   ],
+  session_started: [
+    'sessionId', 'pipelineType', 'mode',
+  ],
+  session_completed: [
+    'sessionId', 'pipelineType', 'mode', 'finalStage',
+    'duration', 'agentCount', 'success',
+  ],
+  token_usage: [
+    'sessionId', 'agent', 'provider', 'model',
+    'inputTokens', 'outputTokens', 'totalTokens', 'estimatedCostUsd',
+  ],
 };
 
 // ---------------------------------------------------------------------------
-// PII blocklist — fields that MUST NEVER appear in telemetry
+// Property Rules (required fields + numeric validation for structured types)
 // ---------------------------------------------------------------------------
 
-const PII_BLOCKLIST = [
-  'path', 'filePath', 'fileName', 'directory', 'cwd',
-  'apiKey', 'token', 'secret', 'password', 'credential',
-  'email', 'username', 'name', 'ip', 'hostname',
-  'content', 'code', 'source', 'prompt', 'message',
-  'stackTrace', 'stack',
+export const EVENT_PROPERTY_RULES = {
+  session_started: {
+    required: ['sessionId', 'pipelineType', 'mode'],
+  },
+  session_completed: {
+    required: ['sessionId', 'pipelineType', 'mode', 'finalStage', 'duration', 'agentCount', 'success'],
+    numeric: ['duration', 'agentCount'],
+  },
+  token_usage: {
+    required: ['sessionId', 'agent', 'provider', 'model', 'inputTokens', 'outputTokens', 'totalTokens', 'estimatedCostUsd'],
+    numeric: ['inputTokens', 'outputTokens', 'totalTokens', 'estimatedCostUsd'],
+  },
+};
+
+// ---------------------------------------------------------------------------
+// PII patterns — fields that MUST NEVER appear in telemetry
+// Regex patterns aligned with chati-telemetry backend (case-insensitive)
+// ---------------------------------------------------------------------------
+
+const PII_PATTERNS = [
+  /^(file_?)?path$/i, /^file_?name$/i, /^dir(ectory)?$/i, /^cwd$/i,
+  /^api_?key$/i, /^(access_?)?token$/i, /^secret$/i, /^pass(word)?$/i,
+  /^cred(ential)?s?$/i, /^e?mail$/i, /^user_?name$/i, /^(full_?)?name$/i,
+  /^ip(_?addr(ess)?)?$/i, /^host_?name$/i, /^(source_?)?code$/i,
+  /^prompt$/i, /^message$/i, /^content$/i, /^stack_?trace$/i,
 ];
 
 // ---------------------------------------------------------------------------
@@ -81,9 +114,9 @@ export function validateEvent(event) {
 
   const props = event.properties || {};
 
-  // Check for PII fields
+  // Check for PII field names (regex-based, aligned with backend)
   for (const key of Object.keys(props)) {
-    if (PII_BLOCKLIST.includes(key)) {
+    if (PII_PATTERNS.some(pattern => pattern.test(key))) {
       errors.push(`PII field detected: "${key}" — must not be included in telemetry`);
     }
   }
@@ -91,7 +124,7 @@ export function validateEvent(event) {
   // Check for PII in values (paths, emails)
   for (const [key, value] of Object.entries(props)) {
     if (typeof value === 'string') {
-      if (value.includes('/Users/') || value.includes('/home/') || value.includes('C:\\Users\\')) {
+      if (/\/users\//i.test(value) || /\\users\\/i.test(value) || /\/home\//i.test(value)) {
         errors.push(`PII detected in "${key}": value contains filesystem path`);
       }
       if (value.includes('@') && value.includes('.')) {
@@ -100,5 +133,21 @@ export function validateEvent(event) {
     }
   }
 
+  // Property-level validation for event types with rules
+  const rules = EVENT_PROPERTY_RULES[event.type];
+  if (rules && props) {
+    const missing = rules.required.filter(key => !(key in props));
+    if (missing.length > 0) {
+      errors.push(`Missing required properties for "${event.type}": ${missing.join(', ')}`);
+    }
+    if (rules.numeric) {
+      for (const key of rules.numeric) {
+        if (key in props && (typeof props[key] !== 'number' || props[key] < 0)) {
+          errors.push(`Property "${key}" must be a non-negative number`);
+        }
+      }
+    }
+  }
+
   return { valid: errors.length === 0, errors };
 }

package/src/terminal/prompt-builder.js

@@ -8,7 +8,7 @@
  * output format instructions.
  */
 
-import { existsSync, readFileSync } from 'fs';
+import { existsSync, readFileSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { runPrism } from '../context/engine.js';
 import { loadHandoff, formatHandoff } from '../tasks/handoff.js';
@@ -16,6 +16,7 @@ import { getWriteScope } from './isolation.js';
 import { resolveOverlayPath } from '../installer/provider-overlay.js';
 import { resolveProviderForAgent } from './cli-registry.js';
 import { buildCompactGotchasSummary } from '../memory/gotchas-injector.js';
+import { estimateTokens } from './cost-tracker.js';
 
 // Import AGENT_MODELS from model-governance (safe — named export,
 // does not trigger main() which is guarded by fileURLToPath check).
@@ -39,6 +40,69 @@ export const AGENT_FILE_MAP = {
   devops: 'chati.dev/agents/deploy/devops.md',
 };
 
+/**
+ * 3-Tier Tool Mesh — Token-aware tool loading profiles per agent.
+ *
+ * T1: Core tools (always loaded) — Read, Write, Edit, Bash, Grep, Glob
+ * T2: On-demand tools (loaded when relevant) — WebSearch, WebFetch, Task
+ * T3: External MCP tools (specialized) — playwright, docker, etc.
+ *
+ * Each agent gets a customized profile based on their role to save
+ * context window budget by not loading unnecessary tool instructions.
+ */
+export const TOOL_PROFILES = {
+  'greenfield-wu': { T1: ['Read', 'Glob', 'Grep', 'Bash'], T2: ['WebSearch'], T3: [] },
+  'brownfield-wu': { T1: ['Read', 'Glob', 'Grep', 'Bash'], T2: ['WebSearch'], T3: [] },
+  brief:     { T1: ['Read', 'Glob', 'Grep'], T2: [], T3: [] },
+  detail:    { T1: ['Read', 'Write', 'Edit', 'Glob', 'Grep'], T2: [], T3: [] },
+  architect: { T1: ['Read', 'Write', 'Edit', 'Glob', 'Grep'], T2: ['WebSearch', 'WebFetch'], T3: [] },
+  ux:        { T1: ['Read', 'Write', 'Edit', 'Glob'], T2: ['WebSearch', 'WebFetch'], T3: [] },
+  phases:    { T1: ['Read', 'Write', 'Edit', 'Glob', 'Grep'], T2: [], T3: [] },
+  tasks:     { T1: ['Read', 'Write', 'Edit', 'Glob', 'Grep'], T2: [], T3: [] },
+  'qa-planning': { T1: ['Read', 'Glob', 'Grep'], T2: [], T3: [] },
+  dev:       { T1: ['Read', 'Write', 'Edit', 'Bash', 'Glob', 'Grep'], T2: ['WebSearch', 'WebFetch', 'Task'], T3: ['playwright'] },
+  'qa-implementation': { T1: ['Read', 'Bash', 'Glob', 'Grep'], T2: ['Task'], T3: [] },
+  devops:    { T1: ['Read', 'Write', 'Edit', 'Bash', 'Glob', 'Grep'], T2: ['WebSearch'], T3: ['docker'] },
+};
+
+/**
+ * Get the tool profile for an agent.
+ *
+ * @param {string} agent - Agent name
+ * @returns {{ T1: string[], T2: string[], T3: string[] }}
+ */
+export function getToolProfile(agent) {
+  return TOOL_PROFILES[agent] || { T1: ['Read', 'Write', 'Edit', 'Bash', 'Glob', 'Grep'], T2: [], T3: [] };
+}
+
+/**
+ * Build tool mesh section for prompt injection.
+ *
+ * @param {string} agent - Agent name
+ * @returns {string} Formatted tool mesh instructions
+ */
+export function buildToolMeshSection(agent) {
+  const profile = getToolProfile(agent);
+  const lines = [
+    '<!-- TOOL MESH -->',
+    '## Available Tools',
+    '',
+    `**Core (T1)**: ${profile.T1.join(', ')}`,
+  ];
+
+  if (profile.T2.length > 0) {
+    lines.push(`**On-demand (T2)**: ${profile.T2.join(', ')} — use only when needed`);
+  }
+
+  if (profile.T3.length > 0) {
+    lines.push(`**External (T3)**: ${profile.T3.join(', ')} — available via MCP if configured`);
+  }
+
+  lines.push('', 'Prefer T1 tools for all standard operations. Use T2/T3 only when the task requires them.');
+
+  return lines.join('\n');
+}
+
 /**
  * @typedef {object} PromptBuildConfig
  * @property {string} agent           - Agent name (e.g. 'detail')
@@ -127,6 +191,9 @@ export function buildAgentPrompt(config) {
 
   const prompt = sections.join('\n\n---\n\n');
 
+  // 10. Prompt size guard — validate before returning
+  const sizeCheck = validatePromptSize(prompt, resolvedProvider);
+
   return {
     prompt,
     model,
@@ -135,6 +202,7 @@ export function buildAgentPrompt(config) {
       agent: config.agent,
       layers: prismResult.layerCount || 0,
       promptSize: prompt.length,
+      sizeCheck,
     },
   };
 }
@@ -176,6 +244,7 @@ function buildPrismSection(config) {
     handoff,
     artifacts: state.artifacts || [],
     taskCriteria: [],
+    userPrompt: config.additionalContext || null,
   });
 
   return {
@@ -292,6 +361,277 @@ function buildSessionSection(config, resolvedModelInfo = {}) {
   return lines.join('\n');
 }
 
+// ---------------------------------------------------------------------------
+// Prompt Size Guard
+// ---------------------------------------------------------------------------
+
+/**
+ * Provider-specific token limits for prompt size validation.
+ */
+const PROVIDER_TOKEN_LIMITS = {
+  claude: 200_000,
+  gemini: 1_000_000,
+  codex: 128_000,
+};
+
+/**
+ * Validate prompt size against provider-specific limits.
+ *
+ * @param {string} prompt - The assembled prompt string
+ * @param {string} [provider='claude'] - Provider name for limit lookup
+ * @returns {{ valid: boolean, level: string, ratio: number, estimatedTokens: number, limit: number, message: string|null }}
+ */
+export function validatePromptSize(prompt, provider = 'claude') {
+  const limit = PROVIDER_TOKEN_LIMITS[provider] || PROVIDER_TOKEN_LIMITS.claude;
+  const tokens = estimateTokens(prompt);
+  const ratio = tokens / limit;
+
+  if (ratio >= 0.9) {
+    return {
+      valid: false,
+      level: 'error',
+      ratio: Math.round(ratio * 100) / 100,
+      estimatedTokens: tokens,
+      limit,
+      message: `Prompt size (${tokens} tokens) exceeds 90% of ${provider} limit (${limit}). Prompt may be truncated or rejected.`,
+    };
+  }
+
+  if (ratio >= 0.7) {
+    return {
+      valid: true,
+      level: 'warning',
+      ratio: Math.round(ratio * 100) / 100,
+      estimatedTokens: tokens,
+      limit,
+      message: `Prompt size (${tokens} tokens) exceeds 70% of ${provider} limit (${limit}). Consider reducing context.`,
+    };
+  }
+
+  return {
+    valid: true,
+    level: 'ok',
+    ratio: Math.round(ratio * 100) / 100,
+    estimatedTokens: tokens,
+    limit,
+    message: null,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Tech Presets
+// ---------------------------------------------------------------------------
+
+/**
+ * Load a tech preset YAML file by stack name.
+ *
+ * @param {string} stack - Stack identifier (e.g., 'nextjs', 'react-vite')
+ * @param {string} projectDir - Project root directory
+ * @returns {{ loaded: boolean, preset: object|null, stack: string }}
+ */
+export function loadPreset(stack, projectDir) {
+  if (!stack || !projectDir) {
+    return { loaded: false, preset: null, stack: stack || '' };
+  }
+
+  // Check both deployed (chati.dev/presets/) and package (framework/presets/) locations
+  const locations = [
+    join(projectDir, 'chati.dev', 'presets'),
+    join(projectDir, 'framework', 'presets'),
+  ];
+
+  for (const presetsDir of locations) {
+    const presetPath = join(presetsDir, `${stack}.yaml`);
+    if (!existsSync(presetPath)) continue;
+
+    try {
+      const raw = readFileSync(presetPath, 'utf-8');
+      const preset = parsePresetYaml(raw);
+      return { loaded: true, preset, stack };
+    } catch {
+      continue;
+    }
+  }
+
+  return { loaded: false, preset: null, stack };
+}
+
+/**
+ * Detect which tech preset to load based on project files.
+ *
+ * @param {string} projectDir - Project root directory
+ * @returns {string|null} Detected stack name or null
+ */
+export function detectPreset(projectDir) {
+  if (!projectDir) return null;
+
+  // Check both deployed and package locations
+  const locations = [
+    join(projectDir, 'chati.dev', 'presets'),
+    join(projectDir, 'framework', 'presets'),
+  ];
+
+  let presetsDir = null;
+  for (const loc of locations) {
+    if (existsSync(loc)) { presetsDir = loc; break; }
+  }
+  if (!presetsDir) return null;
+
+  // List all preset files
+  let presetFiles;
+  try {
+    presetFiles = readdirSync(presetsDir).filter(f => f.endsWith('.yaml'));
+  } catch {
+    return null;
+  }
+
+  // Check package.json dependencies
+  const pkgPath = join(projectDir, 'package.json');
+  let pkgContent = '';
+  if (existsSync(pkgPath)) {
+    try { pkgContent = readFileSync(pkgPath, 'utf-8'); } catch { /* ignore */ }
+  }
+
+  // Check for detection markers in project root
+  for (const file of presetFiles) {
+    const raw = readFileSync(join(presetsDir, file), 'utf-8');
+    const preset = parsePresetYaml(raw);
+    if (!preset.detection || !Array.isArray(preset.detection)) continue;
+
+    for (const marker of preset.detection) {
+      // Check if marker is a file that exists in the project
+      if (existsSync(join(projectDir, marker))) {
+        return preset.stack || file.replace('.yaml', '');
+      }
+      // Check if marker is a dependency
+      if (pkgContent && pkgContent.includes(`"${marker}"`)) {
+        return preset.stack || file.replace('.yaml', '');
+      }
+    }
+  }
+
+  return null;
+}
+
+/**
+ * Parse a preset YAML file into a structured object.
+ * Uses lightweight regex parsing consistent with the framework.
+ *
+ * @param {string} raw - Raw YAML content
+ * @returns {object} Parsed preset
+ */
+export function parsePresetYaml(raw) {
+  const preset = {
+    stack: '',
+    displayName: '',
+    detection: [],
+    conventions: {},
+    structure: [],
+    rules: [],
+  };
+
+  // stack:
+  const stackMatch = raw.match(/^stack:\s*(.+)$/m);
+  if (stackMatch) preset.stack = stackMatch[1].trim();
+
+  // displayName:
+  const nameMatch = raw.match(/^displayName:\s*"?([^"\n]+)"?$/m);
+  if (nameMatch) preset.displayName = nameMatch[1].trim();
+
+  // detection: (array)
+  const detectionMatch = raw.match(/^detection:\s*\n((?:\s+-\s*.+\n?)*)/m);
+  if (detectionMatch) {
+    const items = detectionMatch[1].matchAll(/^\s+-\s*"?([^"\n]+)"?\s*$/gm);
+    for (const item of items) {
+      preset.detection.push(item[1].trim());
+    }
+  }
+
+  // conventions: (key-value map)
+  const convMatch = raw.match(/^conventions:\s*\n((?:\s+\w[\w]*:\s*.+\n?)*)/m);
+  if (convMatch) {
+    const pairs = convMatch[1].matchAll(/^\s+(\w[\w]*):\s*"?([^"\n]+)"?\s*$/gm);
+    for (const pair of pairs) {
+      preset.conventions[pair[1].trim()] = pair[2].trim();
+    }
+  }
+
+  // structure: (array of strings)
+  const structMatch = raw.match(/^structure:\s*\n((?:\s+-\s*.+\n?)*)/m);
+  if (structMatch) {
+    const items = structMatch[1].matchAll(/^\s+-\s*"?([^"\n]+)"?\s*$/gm);
+    for (const item of items) {
+      preset.structure.push(item[1].trim());
+    }
+  }
+
+  // rules: (array of objects with id, text, priority)
+  const rulesMatch = raw.match(/^rules:\s*\n((?:\s+-.+\n(?:\s+\w.+\n?)*)*)/m);
+  if (rulesMatch) {
+    const ruleBlocks = rulesMatch[1].split(/(?=\s+-\s+id:)/);
+    for (const block of ruleBlocks) {
+      const idMatch = block.match(/id:\s*(\S+)/);
+      const textMatch = block.match(/text:\s*"?([^"\n]+)"?/);
+      const prioMatch = block.match(/priority:\s*(\S+)/);
+      if (idMatch && textMatch) {
+        preset.rules.push({
+          id: idMatch[1],
+          text: textMatch[1].trim(),
+          priority: prioMatch ? prioMatch[1] : 'normal',
+        });
+      }
+    }
+  }
+
+  return preset;
+}
+
+/**
+ * Build a formatted preset section for prompt injection.
+ *
+ * @param {object} preset - Parsed preset object
+ * @returns {string} Formatted preset section
+ */
+export function buildPresetSection(preset) {
+  if (!preset) return '';
+
+  const lines = [
+    '<!-- TECH PRESET -->',
+    `## Tech Preset: ${preset.displayName || preset.stack}`,
+    '',
+  ];
+
+  // Conventions
+  if (preset.conventions && Object.keys(preset.conventions).length > 0) {
+    lines.push('### Conventions');
+    for (const [key, value] of Object.entries(preset.conventions)) {
+      lines.push(`- **${key}**: ${value}`);
+    }
+    lines.push('');
+  }
+
+  // Structure
+  if (preset.structure && preset.structure.length > 0) {
+    lines.push('### Expected Structure');
+    for (const item of preset.structure) {
+      lines.push(`- ${item}`);
+    }
+    lines.push('');
+  }
+
+  // Rules
+  if (preset.rules && preset.rules.length > 0) {
+    lines.push('### Rules');
+    for (const rule of preset.rules) {
+      const badge = rule.priority === 'critical' ? '[CRITICAL]' : rule.priority === 'high' ? '[HIGH]' : '';
+      lines.push(`- ${badge ? badge + ' ' : ''}${rule.text}`);
+    }
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
 /**
  * Build output format instructions so the agent produces a parseable handoff.
  */