@rahul05ranjan/dhruv-cli 1.3.0 → 1.5.0

package/dist/core/prompts.js

@@ -0,0 +1,121 @@
+/**
+ * System-message templates per command type. Pure data: no AI plumbing.
+ */
+const SYSTEM_MESSAGES = {
+    explain: `You are a knowledgeable programming instructor and technical expert. Your role is to provide clear, accurate, and practical explanations of technical concepts.
+
+Guidelines:
+- Provide structured explanations with clear sections
+- Use practical examples where helpful
+- Focus on concepts that developers need to understand
+- Avoid unnecessary jargon, but use precise technical terminology
+- Keep responses concise but comprehensive
+- Format code examples clearly
+- Provide context for why something matters
+
+Output Format:
+- Use plain text with clear structure
+- Use bullet points for lists
+- Use numbered steps for procedures
+- Separate code examples with clear labels
+- Avoid markdown formatting except for code blocks when absolutely necessary`,
+    suggest: `You are an expert software architect and senior developer providing actionable recommendations and best practices.
+
+Guidelines:
+- Provide specific, actionable suggestions
+- Prioritize recommendations by importance
+- Include practical implementation steps
+- Mention relevant tools, libraries, or patterns
+- Consider performance, maintainability, and scalability
+- Provide concrete examples where helpful
+- Focus on industry best practices
+
+Output Format:
+- Use clear numbered or bulleted lists
+- Separate different types of suggestions
+- Provide brief explanations for each recommendation
+- Use plain text formatting for better readability`,
+    fix: `You are a debugging expert and problem-solving specialist helping developers resolve technical issues.
+
+Guidelines:
+- Analyze the problem systematically
+- Identify the root cause
+- Provide step-by-step solutions
+- Include preventive measures
+- Show corrected code examples
+- Explain why the fix works
+- Suggest testing approaches
+
+Output Format:
+- Start with problem analysis
+- Provide clear solution steps
+- Show before/after code examples
+- Use plain text with clear structure
+- Avoid complex markdown formatting`,
+    review: `You are a senior code reviewer focused on code quality, best practices, and maintainability.
+
+Guidelines:
+- Analyze code structure and patterns
+- Identify potential issues or improvements
+- Comment on performance implications
+- Suggest refactoring opportunities
+- Check for security considerations
+- Evaluate readability and maintainability
+- Provide constructive feedback
+
+Output Format:
+- Organize feedback by categories (Structure, Performance, Security, etc.)
+- Use clear, actionable language
+- Provide specific line-by-line suggestions where relevant
+- Use plain text formatting for better CLI readability`,
+    optimize: `You are a performance optimization expert specializing in code efficiency and best practices.
+
+Guidelines:
+- Focus on measurable performance improvements
+- Consider different types of optimization (runtime, memory, bundle size, etc.)
+- Provide specific, implementable suggestions
+- Explain the impact of each optimization
+- Consider trade-offs between performance and maintainability
+- Suggest profiling and measurement approaches
+
+Output Format:
+- Categorize optimizations by type
+- Provide clear before/after examples
+- Include estimated impact where possible
+- Use structured plain text formatting`,
+    security: `You are a cybersecurity expert specializing in application security and secure coding practices.
+
+Guidelines:
+- Identify potential security vulnerabilities
+- Provide remediation steps
+- Suggest secure coding patterns
+- Consider common attack vectors
+- Recommend security tools and practices
+- Focus on practical security measures
+- Explain security implications
+
+Output Format:
+- Categorize findings by severity
+- Provide clear remediation steps
+- Use plain text formatting for better readability
+- Include references to security standards where relevant`,
+    generate: `You are a code generation specialist creating high-quality, well-structured code.
+
+Guidelines:
+- Generate clean, readable code
+- Follow established conventions
+- Include appropriate comments
+- Consider edge cases
+- Use proper error handling
+- Follow best practices for the target language
+- Generate comprehensive test cases when requested
+
+Output Format:
+- Provide clean code without excessive markdown
+- Use minimal formatting for better CLI display
+- Include brief explanations only when necessary
+- Focus on practical, working code`,
+};
+export function getSystemMessage(type) {
+    return SYSTEM_MESSAGES[type] ?? SYSTEM_MESSAGES.explain;
+}

package/dist/core/security.d.ts

@@ -0,0 +1,34 @@
+export interface SecurityConfig {
+    enableInputValidation: boolean;
+    enableRateLimiting: boolean;
+    maxInputLength: number;
+    allowedCommands: string[];
+    blockedPatterns: RegExp[];
+    maxRequestsPerMinute: number;
+}
+export declare class SecurityManager {
+    private static instance;
+    private config;
+    private requestCounts;
+    private schemas;
+    private constructor();
+    private initializeSchemas;
+    static getInstance(): SecurityManager;
+    validateInput(command: string, input: any): {
+        valid: boolean;
+        error?: string;
+    };
+    checkRateLimit(identifier: string): {
+        allowed: boolean;
+        remainingRequests: number;
+    };
+    sanitizeInput(input: any): any;
+    auditLog(action: string, details: Record<string, any>): void;
+    getSecurityStatus(): {
+        config: SecurityConfig;
+        activeRateLimits: number;
+        blockedPatternsCount: number;
+    };
+    resetRateLimits(): void;
+}
+export declare const securityManager: SecurityManager;

package/dist/core/security.js

@@ -0,0 +1,197 @@
+import Joi from 'joi';
+import validator from 'validator';
+import { logger, logSecurity } from './logger.js';
+import { metricsCollector } from './metrics.js';
+export class SecurityManager {
+    constructor() {
+        this.requestCounts = new Map();
+        this.schemas = {};
+        this.config = {
+            enableInputValidation: process.env.DHRUV_SECURITY_VALIDATION !== 'false',
+            enableRateLimiting: process.env.DHRUV_SECURITY_RATE_LIMIT !== 'false',
+            maxInputLength: parseInt(process.env.DHRUV_MAX_INPUT_LENGTH || '10000'),
+            allowedCommands: [
+                'explain', 'suggest', 'fix', 'review', 'optimize',
+                'security-check', 'generate', 'init', 'status',
+                'project-type', 'menu', 'completion', 'help'
+            ],
+            blockedPatterns: [
+                /<script\b[^<]*(?:(?!<\/script>)<[^<]*)*<\/script>/gi, // XSS patterns
+                /\b(eval|exec|system|shell_exec|passthru|proc_open|popen)\b/i, // Code execution
+                /\b(rm\s+(-rf|--force)\s+|del\s+)/i, // File deletion
+                /\b(format|fdisk|mkfs)\b/i, // Disk operations
+                /password\s*=\s*['"][^'"]*['"]/i, // Password exposure
+                /\b(ssh|scp|rsync)\s+.*@\w+/i, // SSH operations
+            ],
+            maxRequestsPerMinute: parseInt(process.env.DHRUV_RATE_LIMIT || '60')
+        };
+        this.initializeSchemas();
+        logger.info('Security manager initialized', {
+            config: {
+                ...this.config,
+                blockedPatterns: this.config.blockedPatterns.map(p => p.toString())
+            }
+        });
+    }
+    initializeSchemas() {
+        this.schemas = {
+            explain: Joi.object({
+                query: Joi.string()
+                    .min(1)
+                    .max(this.config.maxInputLength)
+                    .required()
+                    .messages({
+                    'string.empty': 'Query cannot be empty',
+                    'string.max': `Query too long (max ${this.config.maxInputLength} characters)`
+                })
+            }),
+            suggest: Joi.object({
+                query: Joi.string()
+                    .min(1)
+                    .max(this.config.maxInputLength)
+                    .required()
+            }),
+            fix: Joi.object({
+                query: Joi.string()
+                    .min(1)
+                    .max(this.config.maxInputLength)
+                    .required()
+            }),
+            review: Joi.object({
+                fileOrDir: Joi.string()
+                    .min(1)
+                    .max(500)
+                    .pattern(/^[^<>&|;$`]*$/) // Prevent shell injection
+                    .required()
+            }),
+            optimize: Joi.object({
+                file: Joi.string()
+                    .min(1)
+                    .max(500)
+                    .pattern(/^[^<>&|;$`]*$/)
+                    .required()
+            }),
+            generate: Joi.object({
+                type: Joi.string()
+                    .valid('tests', 'documentation', 'docs', 'component')
+                    .required(),
+                target: Joi.string()
+                    .min(1)
+                    .max(500)
+                    .pattern(/^[^<>&|;$`]*$/)
+                    .required()
+            })
+        };
+    }
+    static getInstance() {
+        if (!SecurityManager.instance) {
+            SecurityManager.instance = new SecurityManager();
+        }
+        return SecurityManager.instance;
+    }
+    validateInput(command, input) {
+        if (!this.config.enableInputValidation) {
+            return { valid: true };
+        }
+        try {
+            // Check command is allowed
+            if (!this.config.allowedCommands.includes(command)) {
+                const error = `Command '${command}' is not allowed`;
+                logSecurity('blocked_command', { command, input });
+                metricsCollector.recordError('blocked_command', command);
+                return { valid: false, error };
+            }
+            // Get schema for command
+            const schema = this.schemas[command];
+            if (!schema) {
+                return { valid: true }; // No specific validation for this command
+            }
+            // Validate input
+            const { error } = schema.validate(input, { abortEarly: false });
+            if (error) {
+                const errorMessage = error.details.map((d) => d.message).join(', ');
+                logSecurity('invalid_input', { command, input, error: errorMessage });
+                metricsCollector.recordError('invalid_input', command);
+                return { valid: false, error: errorMessage };
+            }
+            // Check for blocked patterns
+            const inputString = JSON.stringify(input);
+            for (const pattern of this.config.blockedPatterns) {
+                if (pattern.test(inputString)) {
+                    const error = 'Input contains blocked patterns';
+                    logSecurity('blocked_pattern', { command, input, pattern: pattern.toString() });
+                    metricsCollector.recordError('blocked_pattern', command);
+                    return { valid: false, error };
+                }
+            }
+            // Sanitize input
+            const sanitized = this.sanitizeInput(input);
+            if (JSON.stringify(sanitized) !== JSON.stringify(input)) {
+                logger.warn('Input was sanitized', { command, original: input, sanitized });
+            }
+            return { valid: true };
+        }
+        catch (err) {
+            const error = `Validation error: ${err.message}`;
+            logSecurity('validation_error', { command, input, error });
+            metricsCollector.recordError('validation_error', command);
+            return { valid: false, error };
+        }
+    }
+    checkRateLimit(identifier) {
+        if (!this.config.enableRateLimiting) {
+            return { allowed: true, remainingRequests: this.config.maxRequestsPerMinute };
+        }
+        const now = Date.now();
+        const windowStart = Math.floor(now / 60000) * 60000; // 1-minute windows
+        const windowKey = `${identifier}:${windowStart}`;
+        const current = this.requestCounts.get(windowKey) || { count: 0, resetTime: windowStart + 60000 };
+        if (now > current.resetTime) {
+            // Reset window
+            this.requestCounts.set(windowKey, { count: 1, resetTime: windowStart + 60000 });
+            return { allowed: true, remainingRequests: this.config.maxRequestsPerMinute - 1 };
+        }
+        if (current.count >= this.config.maxRequestsPerMinute) {
+            logSecurity('rate_limit_exceeded', { identifier, count: current.count });
+            metricsCollector.recordError('rate_limit_exceeded', 'unknown');
+            return { allowed: false, remainingRequests: 0 };
+        }
+        current.count++;
+        const remaining = Math.max(0, this.config.maxRequestsPerMinute - current.count);
+        return { allowed: true, remainingRequests: remaining };
+    }
+    sanitizeInput(input) {
+        if (typeof input === 'string') {
+            return validator.escape(input);
+        }
+        if (Array.isArray(input)) {
+            return input.map(item => this.sanitizeInput(item));
+        }
+        if (typeof input === 'object' && input !== null) {
+            const sanitized = {};
+            for (const [key, value] of Object.entries(input)) {
+                sanitized[key] = this.sanitizeInput(value);
+            }
+            return sanitized;
+        }
+        return input;
+    }
+    auditLog(action, details) {
+        logSecurity(action, {
+            timestamp: new Date().toISOString(),
+            ...details
+        });
+    }
+    getSecurityStatus() {
+        return {
+            config: this.config,
+            activeRateLimits: this.requestCounts.size,
+            blockedPatternsCount: this.config.blockedPatterns.length
+        };
+    }
+    resetRateLimits() {
+        this.requestCounts.clear();
+        logger.info('Rate limits reset');
+    }
+}
+export const securityManager = SecurityManager.getInstance();

package/dist/index.js

@@ -11,9 +11,17 @@ import { optimize } from './commands/optimize.js';
 import { securityCheck } from './commands/security-check.js';
 import { generate } from './commands/generate.js';
 import { init } from './commands/init.js';
+import { status } from './commands/status.js';
+import { health } from './commands/health.js';
+import { metrics } from './commands/metrics.js';
 import { detectProjectType } from './utils/projectType.js';
 import { menu } from './commands/menu.js';
-import pkg from '../package.json' assert { type: 'json' };
+import { createRequire } from 'module';
+import { logger, logInfo, logError } from './core/logger.js';
+import { metricsCollector } from './core/metrics.js';
+import { commandDescription, completionCommands, completionOptions } from './core/command-catalog.js';
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
 const program = new Command();
 program
     .name('dhruv')
@@ -21,54 +29,78 @@ program
     .version(pkg.version);
 program
     .command('explain <query>')
-    .description('Explain a concept or command')
+    .description(commandDescription('explain'))
+    .addHelpText('after', '\nExamples:\n  $ dhruv explain "What is async/await?"\n  $ dhruv explain "Docker containers vs VMs"')
     .action(explain);
 program
     .command('suggest <query>')
-    .description('Get AI-powered suggestions')
+    .description(commandDescription('suggest'))
+    .addHelpText('after', '\nExamples:\n  $ dhruv suggest "React performance optimization"\n  $ dhruv suggest "Node.js project structure"')
     .action(suggest);
 program
     .command('fix <query>')
-    .description('Get a fix for a coding issue or error')
+    .description(commandDescription('fix'))
+    .addHelpText('after', '\nExamples:\n  $ dhruv fix "TypeError: Cannot read property of undefined"\n  $ dhruv fix "CORS error in Express.js"')
     .action(fix);
 program
     .command('review <fileOrDir>')
-    .description('Review code in a file or directory')
-    .action(review);
+    .description(commandDescription('review'))
+    .option('--diff', 'Review the current uncommitted git diff')
+    .action((fileOrDir, command) => review(fileOrDir, command.opts()));
 program
     .command('optimize <file>')
-    .description('Optimize a file (e.g., package.json)')
+    .description(commandDescription('optimize'))
     .action(optimize);
 program
     .command('security-check [fileOrDir]')
-    .description('Run a security check on code')
-    .action(securityCheck);
+    .description(commandDescription('security-check'))
+    .option('--strict', 'Exit with failure when high-confidence findings are detected')
+    .action((fileOrDir, command) => securityCheck(fileOrDir, command.opts()));
 program
     .command('generate <type> <target>')
-    .description('Generate code/tests for a file')
-    .action(generate);
+    .description(commandDescription('generate'))
+    .option('--apply', 'Write generated tests to disk (preview is the default)')
+    .option('--output <path>', 'Write generated tests to this path')
+    .option('--overwrite', 'Allow replacing an existing output file')
+    .action((type, target, command) => generate(type, target, command.opts()));
 program
     .command('init')
-    .description('Interactive setup/configuration wizard')
+    .description(commandDescription('init'))
     .action(init);
+program
+    .command('status')
+    .description(commandDescription('status'))
+    .action(status);
+program
+    .command('health')
+    .description(commandDescription('health'))
+    .option('--details', 'Show every health check and diagnostic detail')
+    .action((command) => health(command.opts()));
+program
+    .command('metrics')
+    .description(commandDescription('metrics'))
+    .option('--raw', 'Export raw Prometheus metrics')
+    .option('--reset', 'Clear persisted local metrics')
+    .action((command) => metrics(command.opts()));
 program
     .command('project-type')
-    .description('Detect and print the current project type')
+    .description(commandDescription('project-type'))
     .action(() => {
     const type = detectProjectType();
     console.log(chalk.blue(`Detected project type: ${type}`));
 });
 program
     .command('menu')
-    .description('Interactive command palette')
+    .description(commandDescription('menu'))
     .action(menu);
 program
     .option('--model <model>', 'Set Ollama model')
     .option('--verbose', 'Enable verbose output')
     .option('--json', 'Output in JSON format')
+    .option('--timeout <milliseconds>', 'Set the AI request timeout')
     .hook('preAction', async (thisCommand) => {
     const opts = thisCommand.opts();
-    if (opts.model || opts.verbose || opts.json) {
+    if (opts.model || opts.verbose || opts.json || opts.timeout) {
         const config = {};
         if (opts.model)
             config.model = opts.model;
@@ -76,6 +108,8 @@ program
             config.verbose = true;
         if (opts.json)
             config.responseFormat = 'json';
+        if (opts.timeout)
+            config.timeoutMs = Number(opts.timeout);
         // Save config for session
         const configModule = await import('./config/config.js');
         configModule.saveConfig(config);
@@ -102,29 +136,57 @@ async function loadPlugins(program) {
     }
 }
 (async () => {
-    await loadPlugins(program);
-    program.parse(process.argv);
+    // Initialize enterprise features
+    try {
+        logInfo('Dhruv CLI starting', {
+            version: pkg.version,
+            nodeVersion: process.version,
+            platform: process.platform
+        });
+        // Record session start
+        metricsCollector.recordSession();
+        await loadPlugins(program);
+        program.parse(process.argv);
+        // Record successful session
+        const sessionId = logger.getSessionId();
+        logInfo('CLI session completed', { sessionId });
+    }
+    catch (error) {
+        logError('CLI startup failed', error);
+        console.error(chalk.red('Failed to start Dhruv CLI:'), error.message);
+        process.exit(1);
+    }
 })();
 // Autocomplete: Generate shell completion scripts
 program
     .command('completion')
-    .description('Generate shell completion script')
+    .description(commandDescription('completion'))
     .argument('[shell]', 'shell type (bash|zsh|fish)', 'bash')
     .action((shell) => {
+    const commands = completionCommands();
+    const options = completionOptions();
     let script = '';
     switch (shell) {
         case 'zsh':
-            script = `#compdef dhruv\n_dhruv_completion() {\n  reply=( $(dhruv --help | awk '/Commands:/,/^$/ {if(NR>1)print $1}') )\n}\ncompctl -K _dhruv_completion dhruv`;
+            script = `#compdef dhruv\n_dhruv_completion() {\n  _arguments '1:command:(${commands})' '*:option:(${options})'\n}\ncompdef _dhruv_completion dhruv`;
             break;
         case 'fish':
-            script = `function __fish_dhruv_complete\n  dhruv --help | awk '/Commands:/,/^$/ {if(NR>1)print $1}'\nend\ncomplete -c dhruv -a '(__fish_dhruv_complete)'`;
+            script = `complete -c dhruv -f -n '__fish_use_subcommand' -a '${commands}'\ncomplete -c dhruv -f -n 'not __fish_use_subcommand' -a '${options}'`;
             break;
-        default:
+        case 'bash':
             script = String.raw `#!/bin/bash
 _dhruv_completion() {
-  COMPREPLY=( $(compgen -W "$(dhruv --help | awk '/Commands:/,/^$/ {if(NR>1)print $1}')" -- \${COMP_WORDS[1]}) )
+  local commands="${commands}"
+  local options="${options}"
+  local choices="$commands $options"
+  COMPREPLY=( $(compgen -W "$choices" -- "\${COMP_WORDS[COMP_CWORD]}") )
 }
 complete -F _dhruv_completion dhruv`;
+            break;
+        default:
+            console.error(chalk.red(`Unsupported shell "${shell}". Choose bash, zsh, or fish.`));
+            process.exitCode = 2;
+            return;
     }
     console.log(script);
     console.log(`\n# To enable tab completion, add the above to your shell profile or source it directly.`);

package/dist/utils/projectType.d.ts

@@ -1 +1 @@
-export declare function detectProjectType(): string;
+export declare function detectProjectType(directory?: string): string;

package/dist/utils/projectType.js

@@ -1,17 +1,36 @@
 // Use .js extension for ESM compatibility
 import fs from 'fs';
-export function detectProjectType() {
-    if (fs.existsSync('package.json')) {
-        const pkg = JSON.parse(fs.readFileSync('package.json', 'utf-8'));
-        if (pkg.dependencies?.react || pkg.devDependencies?.react)
+import path from 'path';
+export function detectProjectType(directory = process.cwd()) {
+    const file = (name) => path.join(directory, name);
+    if (fs.existsSync(file('package.json'))) {
+        let pkg;
+        try {
+            pkg = JSON.parse(fs.readFileSync(file('package.json'), 'utf-8'));
+        }
+        catch {
+            return 'unknown';
+        }
+        const dependencies = { ...pkg.dependencies, ...pkg.devDependencies };
+        if (dependencies.react)
             return 'react';
-        if (pkg.dependencies?.express || pkg.devDependencies?.express)
+        if (dependencies.next)
+            return 'nextjs';
+        if (dependencies.express)
             return 'node-express';
+        if (dependencies.typescript || fs.existsSync(file('tsconfig.json')))
+            return 'node-typescript';
         return 'node';
     }
-    if (fs.existsSync('requirements.txt'))
+    if (fs.existsSync(file('requirements.txt')))
         return 'python';
-    if (fs.existsSync('pyproject.toml'))
+    if (fs.existsSync(file('pyproject.toml')))
         return 'python';
+    if (fs.existsSync(file('go.mod')))
+        return 'go';
+    if (fs.existsSync(file('Cargo.toml')))
+        return 'rust';
+    if (fs.existsSync(file('pom.xml')) || fs.existsSync(file('build.gradle')))
+        return 'java';
     return 'unknown';
 }

package/dist/utils/ux.d.ts

@@ -1,5 +1,8 @@
 export declare function highlightCode(code: string, lang?: string): string;
 export declare function printError(message: string): void;
 export declare function printSuccess(message: string): void;
+export declare function printWarning(message: string): void;
+export declare function printInfo(message: string): void;
+export declare function createSpinner(text: string): import("ora").Ora;
 export declare function createProgressBar(total: number): any;
 export declare function themed(text: string, type?: 'primary' | 'accent'): string;

package/dist/utils/ux.js

@@ -2,6 +2,7 @@ import chalk from 'chalk';
 // @ts-expect-error: cli-progress has no type definitions
 import cliProgress from 'cli-progress';
 import { highlight } from 'cli-highlight';
+import ora from 'ora';
 import { loadConfig } from '../config/config.js';
 function getTheme() {
     const config = loadConfig();
@@ -27,6 +28,20 @@ export function printSuccess(message) {
     const { success } = getTheme();
     console.log(success(' SUCCESS '), success(message));
 }
+export function printWarning(message) {
+    const { accent } = getTheme();
+    console.warn(chalk.bgYellow.black(' WARNING '), accent(message));
+}
+export function printInfo(message) {
+    const { primary } = getTheme();
+    console.log(chalk.bgBlue.white(' INFO '), primary(message));
+}
+export function createSpinner(text) {
+    return ora({
+        text: themed(text, 'primary'),
+        color: 'cyan',
+    });
+}
 export function createProgressBar(total) {
     const { primary } = getTheme();
     const bar = new cliProgress.SingleBar({

package/docs/agents/domain.md

@@ -0,0 +1,51 @@
+# Domain Docs
+
+How the engineering skills should consume this repo's domain documentation when exploring the codebase.
+
+## Before exploring, read these
+
+- **`CONTEXT.md`** at the repo root, or
+- **`CONTEXT-MAP.md`** at the repo root if it exists: it points at one `CONTEXT.md` per context. Read each one relevant to the topic.
+- **`docs/adr/`**: read ADRs that touch the area you're about to work in. In multi-context repos, also check `src/<context>/docs/adr/` for context-scoped decisions.
+
+If any of these files don't exist, **proceed silently**. Don't flag their absence; don't suggest creating them upfront. The `/domain-modeling` skill (reached via `/grill-with-docs` and `/improve-codebase-architecture`) creates them lazily when terms or decisions actually get resolved.
+
+## File structure
+
+Single-context repo (most repos):
+
+```
+/
+├── CONTEXT.md
+├── docs/adr/
+│   ├── 0001-event-sourced-orders.md
+│   └── 0002-postgres-for-write-model.md
+└── src/
+```
+
+Multi-context repo (presence of `CONTEXT-MAP.md` at the root):
+
+```
+/
+├── CONTEXT-MAP.md
+├── docs/adr/                          ← system-wide decisions
+└── src/
+    ├── ordering/
+    │   ├── CONTEXT.md
+    │   └── docs/adr/                  ← context-specific decisions
+    └── billing/
+        ├── CONTEXT.md
+        └── docs/adr/
+```
+
+## Use the glossary's vocabulary
+
+When your output names a domain concept (in an issue title, a refactor proposal, a hypothesis, a test name), use the term as defined in `CONTEXT.md`. Don't drift to synonyms the glossary explicitly avoids.
+
+If the concept you need isn't in the glossary yet, that's a signal: either you're inventing language the project doesn't use (reconsider) or there's a real gap (note it for `/domain-modeling`).
+
+## Flag ADR conflicts
+
+If your output contradicts an existing ADR, surface it explicitly rather than silently overriding:
+
+> _Contradicts ADR-0007 (event-sourced orders), but worth reopening because…_