universal-dev-standards 4.2.0 → 5.0.0-beta.10

package/src/utils/reference-sync.js

@@ -9,21 +9,26 @@
  * Based on standards-registry.json and RULE_TEMPLATES in integration-generator.js
  */
 export const CATEGORY_TO_STANDARDS = {
-  'anti-hallucination': ['core/anti-hallucination.md'],
+  'anti-hallucination': ['core/anti-hallucination.md', 'core/guides/anti-hallucination-guide.md'],
   'commit-standards': ['core/commit-message-guide.md'],
   'code-review': ['core/code-review-checklist.md', 'core/checkin-standards.md'],
-  'spec-driven-development': ['core/spec-driven-development.md'],
-  'testing': ['core/testing-standards.md'],
+  'spec-driven-development': ['core/spec-driven-development.md', 'methodologies/guides/sdd-guide.md'],
+  'testing': ['core/testing-standards.md', 'skills/testing-guide/testing-theory.md'],
   'documentation': ['core/documentation-structure.md'],
-  'git-workflow': ['core/git-workflow.md'],
+  'git-workflow': ['core/git-workflow.md', 'core/guides/git-workflow-guide.md'],
   'error-handling': ['core/error-code-standards.md', 'core/logging-standards.md'],
-  'project-structure': ['core/project-structure.md']
+  'project-structure': ['core/project-structure.md'],
+  'refactoring': ['core/refactoring-standards.md', 'core/guides/refactoring-guide.md'],
+  'requirement': ['core/requirement-engineering.md', 'methodologies/guides/requirement-engineering-guide.md'],
+  'developer-memory': ['core/developer-memory.md'],
+  'project-context-memory': ['core/project-context-memory.md']
 };
 
 /**
  * Reverse mapping from standard filename to category ID
  */
 export const STANDARD_TO_CATEGORY = {
+  // Core Rules (human .md format)
   'anti-hallucination.md': 'anti-hallucination',
   'commit-message-guide.md': 'commit-standards',
   'code-review-checklist.md': 'code-review',
@@ -34,7 +39,34 @@ export const STANDARD_TO_CATEGORY = {
   'git-workflow.md': 'git-workflow',
   'error-code-standards.md': 'error-handling',
   'logging-standards.md': 'error-handling',
-  'project-structure.md': 'project-structure'
+  'project-structure.md': 'project-structure',
+  'refactoring-standards.md': 'refactoring',
+  'requirement-engineering.md': 'requirement',
+  'developer-memory.md': 'developer-memory',
+  'project-context-memory.md': 'project-context-memory',
+  // Core Rules (AI .ai.yaml format)
+  'anti-hallucination.ai.yaml': 'anti-hallucination',
+  'commit-message.ai.yaml': 'commit-standards',
+  'code-review.ai.yaml': 'code-review',
+  'checkin-standards.ai.yaml': 'code-review',
+  'spec-driven-development.ai.yaml': 'spec-driven-development',
+  'testing.ai.yaml': 'testing',
+  'documentation-structure.ai.yaml': 'documentation',
+  'git-workflow.ai.yaml': 'git-workflow',
+  'error-codes.ai.yaml': 'error-handling',
+  'logging.ai.yaml': 'error-handling',
+  'project-structure.ai.yaml': 'project-structure',
+  'refactoring-standards.ai.yaml': 'refactoring',
+  'requirement-engineering.ai.yaml': 'requirement',
+  'developer-memory.ai.yaml': 'developer-memory',
+  'project-context-memory.ai.yaml': 'project-context-memory',
+  // Guides (educational content)
+  'anti-hallucination-guide.md': 'anti-hallucination',
+  'sdd-guide.md': 'spec-driven-development',
+  'testing-theory.md': 'testing',
+  'git-workflow-guide.md': 'git-workflow',
+  'refactoring-guide.md': 'refactoring',
+  'requirement-engineering-guide.md': 'requirement'
 };
 
 /**
@@ -92,26 +124,43 @@ export function getStandardCategory(sourcePath) {
  *   - syncedRefs: Standards that are properly synced
  */
 export function compareStandardsWithReferences(manifestStandards, integrationReferences) {
-  // Get filenames from manifest standards (only those that have category mappings)
-  const manifestFileNames = new Set();
+  // Compare at category level to handle .md vs .ai.yaml format differences
+  // e.g., manifest has 'anti-hallucination.ai.yaml' but integration references 'anti-hallucination.md'
+  const manifestCategories = new Set();
   for (const std of manifestStandards) {
     const fileName = std.split('/').pop();
-    // Only include standards that are part of the category system
-    if (STANDARD_TO_CATEGORY[fileName]) {
-      manifestFileNames.add(fileName);
+    const category = STANDARD_TO_CATEGORY[fileName];
+    if (category) {
+      manifestCategories.add(category);
     }
   }
 
-  const refSet = new Set(integrationReferences);
-
-  // References in integration file but not in manifest
-  const orphanedRefs = integrationReferences.filter(ref => !manifestFileNames.has(ref));
+  // References in integration file but not backed by any manifest standard (by category)
+  const orphanedRefs = integrationReferences.filter(ref => {
+    const category = STANDARD_TO_CATEGORY[ref];
+    return !category || !manifestCategories.has(category);
+  });
 
-  // Standards in manifest but not referenced
-  const missingRefs = [...manifestFileNames].filter(fileName => !refSet.has(fileName));
+  // Categories in manifest but not referenced in integration file
+  const refCategories = new Set();
+  for (const ref of integrationReferences) {
+    const category = STANDARD_TO_CATEGORY[ref];
+    if (category) {
+      refCategories.add(category);
+    }
+  }
+  const missingCategories = [...manifestCategories].filter(cat => !refCategories.has(cat));
+  // Convert missing categories back to representative filenames for reporting
+  const missingRefs = missingCategories.flatMap(cat => {
+    const paths = CATEGORY_TO_STANDARDS[cat] || [];
+    return paths.map(p => p.split('/').pop());
+  });
 
   // Properly synced references
-  const syncedRefs = integrationReferences.filter(ref => manifestFileNames.has(ref));
+  const syncedRefs = integrationReferences.filter(ref => {
+    const category = STANDARD_TO_CATEGORY[ref];
+    return category && manifestCategories.has(category);
+  });
 
   return { orphanedRefs, missingRefs, syncedRefs };
 }
@@ -182,7 +231,8 @@ export function getToolFromPath(integrationPath) {
     '.github/copilot-instructions.md': 'copilot',
     'INSTRUCTIONS.md': 'antigravity',
     'CLAUDE.md': 'claude-code',
-    '.standards/CLAUDE.md': 'claude-code'
+    '.standards/CLAUDE.md': 'claude-code',
+    'AGENTS.md': 'codex'
   };
 
   return pathToTool[integrationPath] || null;

package/src/utils/skills-installer.js

@@ -29,12 +29,12 @@ const BUNDLED_DIR = join(CLI_ROOT, 'bundled');
  * @returns {string} Path to skills source directory
  */
 function getSkillsSourceDir() {
-  const bundledPath = join(BUNDLED_DIR, 'skills', 'claude-code');
+  const bundledPath = join(BUNDLED_DIR, 'skills');
   if (existsSync(bundledPath)) {
     return bundledPath;
   }
   // Development environment fallback
-  return join(CLI_ROOT, '..', 'skills', 'claude-code');
+  return join(CLI_ROOT, '..', 'skills');
 }
 
 const SKILLS_LOCAL_DIR = getSkillsSourceDir();
@@ -75,9 +75,12 @@ export function getAvailableCommandNames() {
     return [];
   }
 
+  // Files to exclude from command list
+  const EXCLUDED_FILES = ['README.md', 'COMMAND-FAMILY-OVERVIEW.md'];
+
   try {
     return readdirSync(COMMANDS_LOCAL_DIR)
-      .filter(file => file.endsWith('.md') && file !== 'README.md')
+      .filter(file => file.endsWith('.md') && !EXCLUDED_FILES.includes(file))
       .map(file => basename(file, '.md'));
   } catch {
     return [];

package/src/utils/standard-fixer.js

@@ -0,0 +1,141 @@
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+import { exec } from 'child_process';
+import util from 'util';
+import { pathToFileURL } from 'node:url';
+import { StandardValidator } from './standard-validator.js';
+
+const execAsync = util.promisify(exec);
+
+export class StandardFixer {
+  constructor(projectPath) {
+    this.projectPath = projectPath;
+    this.validator = new StandardValidator(projectPath);
+    this.standardsDir = path.join(projectPath, '.standards');
+  }
+
+  /**
+   * Attempt to fix a standard violation
+   * @param {string} standardId - The ID of the standard
+   * @returns {Promise<Object>} Fix result
+   */
+  async fix(standardId) {
+    // 1. Check if already valid
+    const preCheck = await this.validator.validate(standardId);
+    if (preCheck.success) {
+      return { success: true, message: 'Standard is already valid.', status: 'skipped' };
+    }
+
+    // 2. Find standard file
+    const standardFile = this.validator.findStandardFile(standardId);
+    if (!standardFile) {
+      return { success: false, message: `Standard '${standardId}' not found.` };
+    }
+
+    // 3. Load config
+    let standardConfig;
+    try {
+      standardConfig = yaml.load(fs.readFileSync(standardFile, 'utf-8'));
+    } catch (e) {
+      return { success: false, message: `Failed to parse standard: ${e.message}` };
+    }
+
+    if (!standardConfig.physical_spec || !standardConfig.physical_spec.fixer) {
+      return { 
+        success: false, 
+        message: `Standard '${standardId}' does not have a fixer defined.`,
+        status: 'no_fixer'
+      };
+    }
+
+    const { fixer } = standardConfig.physical_spec;
+
+    // 4. Execute Fixer
+    try {
+      if (fixer.type === 'command') {
+        if (!fixer.command) throw new Error('Fixer type is command but no command provided');
+        await execAsync(fixer.command, { cwd: this.projectPath });
+      } else if (fixer.type === 'copy_template') {
+        await this.executeCopyTemplate(fixer);
+      } else if (fixer.type === 'script_file') {
+        await this.executeScriptFixer(fixer, standardConfig);
+      } else {
+        throw new Error(`Unknown fixer type: ${fixer.type}`);
+      }
+    } catch (e) {
+      return { 
+        success: false, 
+        message: `Fix execution failed: ${e.message}`,
+        details: e.stderr || e.stdout || e.stack
+      };
+    }
+
+    // 5. Verify Fix
+    const postCheck = await this.validator.validate(standardId);
+    if (postCheck.success) {
+      return { success: true, message: 'Fix applied and verified successfully.', status: 'fixed' };
+    } else {
+      return { 
+        success: false, 
+        message: 'Fix applied but validation still failed.', 
+        details: postCheck.message,
+        status: 'partial'
+      };
+    }
+  }
+
+  async executeScriptFixer(fixerConfig, standardConfig) {
+    const { script_path } = fixerConfig;
+    if (!script_path) throw new Error('Missing script_path for script_file fixer');
+
+    // Resolve script path
+    let fullScriptPath = path.join(this.standardsDir, 'fixers', script_path);
+    if (!fs.existsSync(fullScriptPath)) {
+      fullScriptPath = path.join(this.projectPath, script_path);
+    }
+
+    if (!fs.existsSync(fullScriptPath)) {
+      throw new Error(`Fixer script not found: ${fullScriptPath}`);
+    }
+
+    // Dynamic import
+    const module = await import(pathToFileURL(fullScriptPath).href);
+    if (typeof module.fix !== 'function') {
+      throw new Error('Fixer script must export a fix() function');
+    }
+
+    await module.fix({
+      projectPath: this.projectPath,
+      config: standardConfig
+    });
+  }
+
+  async executeCopyTemplate(fixer) {
+    if (!fixer.template_file || !fixer.destination) {
+      throw new Error('Missing template_file or destination for copy_template fixer');
+    }
+
+    // Resolve template path
+    // Priority: 1. Project .standards/templates/ 2. Absolute/Relative from standards dir
+    let templatePath = path.join(this.standardsDir, 'templates', fixer.template_file);
+    if (!fs.existsSync(templatePath)) {
+        // Fallback: try relative to standard file location? Or just relative to project root?
+        templatePath = path.join(this.projectPath, fixer.template_file);
+    }
+    
+    if (!fs.existsSync(templatePath)) {
+        throw new Error(`Template file not found: ${templatePath}`);
+    }
+
+    const destPath = path.join(this.projectPath, fixer.destination);
+    
+    // Ensure dest dir exists
+    const destDir = path.dirname(destPath);
+    if (!fs.existsSync(destDir)) {
+      fs.mkdirSync(destDir, { recursive: true });
+    }
+
+    fs.copyFileSync(templatePath, destPath);
+  }
+}

package/src/utils/standard-validator.js

@@ -0,0 +1,329 @@
+import fs from 'fs';
+import path from 'path';
+import yaml from 'js-yaml';
+import { exec } from 'child_process';
+import util from 'util';
+import { pathToFileURL } from 'node:url';
+import { readManifest } from './copier.js';
+
+const execAsync = util.promisify(exec);
+
+export class StandardValidator {
+  constructor(projectPath) {
+    this.projectPath = projectPath;
+    this.standardsDir = path.join(projectPath, '.standards');
+  }
+
+  /**
+   * Validate a specific standard by ID
+   * @param {string} standardId - The ID of the standard (e.g., 'project-structure')
+   * @returns {Promise<Object>} Validation result { success: boolean, message: string, details: any }
+   */
+  async validate(standardId) {
+    // 1. Find the standard file
+    const standardFile = this.findStandardFile(standardId);
+    if (!standardFile) {
+      return {
+        success: false,
+        message: `Standard '${standardId}' is not installed in this project.`
+      };
+    }
+
+    // 2. Parse the standard
+    let standardConfig;
+    try {
+      const content = fs.readFileSync(standardFile, 'utf-8');
+      standardConfig = yaml.load(content);
+    } catch (e) {
+      return {
+        success: false,
+        message: `Failed to parse standard file: ${e.message}`
+      };
+    }
+
+    // 3. Check for physical_spec
+    // Support both root-level (legacy v2 draft) and standard-level (v2 spec) physical_spec?
+    // Spec says: { standard: ..., physical_spec: ... } at root.
+    if (!standardConfig.physical_spec) {
+      return {
+        success: true,
+        message: `Standard '${standardId}' does not have a Physical Spec defined. Skipped validation.`, 
+        skipped: true
+      };
+    }
+
+    const { type, validator, schema } = standardConfig.physical_spec;
+
+    // 4. Execute Validation Logic based on type
+    try {
+      switch (type) {
+        case 'filesystem_schema':
+          return await this.validateFilesystem(schema, validator);
+        case 'json_schema':
+          return { success: false, message: 'JSON Schema validation not yet implemented' };
+        case 'script_file':
+          return await this.executeScriptValidator(validator, standardConfig);
+        default:
+           // If a generic command validator is present, use it
+           if (validator && validator.command) {
+             return await this.runCommandValidator(validator);
+           }
+           return { success: false, message: `Unknown physical spec type: ${type}` };
+      }
+    } catch (error) {
+       return {
+         success: false,
+         message: `Validation execution failed: ${error.message}`
+       };
+    }
+  }
+
+  /**
+   * Check if a filename potentially matches the requested standardId
+   * @param {string} basename - File basename (without extension)
+   * @param {string} standardId - Requested standard ID
+   * @returns {boolean} True if potential match
+   */
+  _isPotentialMatch(basename, standardId) {
+    // Clean basename: remove .ai suffix if present
+    const cleanBasename = basename.endsWith('.ai')
+      ? basename.slice(0, -3)
+      : basename;
+
+    // 1. Exact match
+    if (cleanBasename === standardId) {
+      return true;
+    }
+
+    // 2. Suffix-removed match: e.g., "security" matches "security-standards"
+    const suffixes = ['-standards', '-guide'];
+    for (const suffix of suffixes) {
+      if (cleanBasename.endsWith(suffix)) {
+        const withoutSuffix = cleanBasename.slice(0, -suffix.length);
+        if (withoutSuffix === standardId) {
+          return true;
+        }
+      }
+    }
+
+    // 3. Prefix match: basename starts with standardId followed by dash
+    if (cleanBasename.startsWith(`${standardId}-`)) {
+      return true;
+    }
+
+    return false;
+  }
+
+  /**
+   * Verify if the file's internal standard.id matches the requested ID
+   * @param {string} filePath - Full path to the standard file
+   * @param {string} standardId - Requested standard ID
+   * @returns {boolean} True if internal ID matches
+   */
+  _verifyInternalId(filePath, standardId) {
+    try {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      const data = yaml.load(content);
+
+      // Check standard.id field (Ground Truth)
+      if (data && data.standard && data.standard.id === standardId) {
+        return true;
+      }
+
+      // Also accept if no internal ID is defined (backward compatibility)
+      // In this case, rely on filename matching
+      if (!data || !data.standard || !data.standard.id) {
+        return true;
+      }
+
+      return false;
+    } catch {
+      // If file cannot be parsed, rely on filename matching
+      return true;
+    }
+  }
+
+  findStandardFile(standardId) {
+    // 1. Try to locate via manifest first (Smart ID Resolution)
+    const manifest = readManifest(this.projectPath);
+    if (manifest) {
+      // Combine standards and extensions arrays for searching
+      const allFiles = [
+        ...(Array.isArray(manifest.standards) ? manifest.standards : []),
+        ...(Array.isArray(manifest.extensions) ? manifest.extensions : [])
+      ];
+
+      for (const filePath of allFiles) {
+        const basename = path.basename(filePath, path.extname(filePath));
+
+        // Check if this file is a potential match
+        if (this._isPotentialMatch(basename, standardId)) {
+          const fullPath = path.join(this.projectPath, filePath);
+
+          if (fs.existsSync(fullPath)) {
+            // Verify via internal standard.id (Ground Truth)
+            if (this._verifyInternalId(fullPath, standardId)) {
+              return fullPath;
+            }
+          }
+        }
+      }
+    }
+
+    // 2. Fallback: direct name check in .standards/ directory
+    // Try exact match first
+    const exactAiPath = path.join(this.standardsDir, `${standardId}.ai.yaml`);
+    if (fs.existsSync(exactAiPath)) return exactAiPath;
+
+    // Try with common suffixes
+    const suffixes = ['-standards', '-guide'];
+    for (const suffix of suffixes) {
+      const suffixedPath = path.join(this.standardsDir, `${standardId}${suffix}.ai.yaml`);
+      if (fs.existsSync(suffixedPath)) {
+        if (this._verifyInternalId(suffixedPath, standardId)) {
+          return suffixedPath;
+        }
+      }
+    }
+
+    // Try .md (less likely to have physical spec, but possible in hybrid future)
+    const mdPath = path.join(this.standardsDir, `${standardId}.md`);
+    if (fs.existsSync(mdPath)) return mdPath;
+
+    return null;
+  }
+
+  async runCommandValidator(validator) {
+    const { command, rule } = validator;
+    try {
+      const { stdout } = await execAsync(command, { cwd: this.projectPath });
+      return {
+        success: true,
+        message: `Passed rule: ${rule}`,
+        details: stdout.trim()
+      };
+    } catch (e) {
+      return {
+        success: false,
+        message: `Failed rule: ${rule}`,
+        details: e.message + (e.stderr ? `\nStderr: ${e.stderr}` : '')
+      };
+    }
+  }
+
+  async validateFilesystem(schema, validator) {
+    // If validator command is provided, use it primarily
+    if (validator && validator.command) {
+      return await this.runCommandValidator(validator);
+    }
+
+    // Native Node.js validation for cross-platform stability
+    const missing = [];
+    
+    // Check required directories
+    if (schema && schema.root && schema.root.required) {
+      for (const dir of schema.root.required) {
+        if (!fs.existsSync(path.join(this.projectPath, dir))) {
+          missing.push(dir);
+        }
+      }
+    } else if (!schema) {
+       return { success: false, message: 'No filesystem schema defined' };
+    }
+    
+    if (missing.length > 0) {
+      return {
+        success: false,
+        message: `Missing required directories: ${missing.join(', ')}`
+      };
+    }
+    
+    return {
+      success: true,
+      message: 'Project structure matches required schema.'
+    };
+  }
+
+  async executeScriptValidator(validatorConfig, standardConfig) {
+    const { script_path } = validatorConfig;
+    if (!script_path) throw new Error('Missing script_path for script_file validator');
+
+    // Resolve script path
+    let fullScriptPath = path.join(this.standardsDir, 'validators', script_path);
+    if (!fs.existsSync(fullScriptPath)) {
+      fullScriptPath = path.join(this.projectPath, script_path);
+    }
+
+    if (!fs.existsSync(fullScriptPath)) {
+      throw new Error(`Validator script not found: ${fullScriptPath}`);
+    }
+
+    try {
+      // Dynamic import
+      const module = await import(pathToFileURL(fullScriptPath).href);
+      if (typeof module.validate !== 'function') {
+        throw new Error('Validator script must export a validate() function');
+      }
+
+      return await module.validate({
+        projectPath: this.projectPath,
+        config: standardConfig
+      });
+    } catch (e) {
+      return {
+        success: false,
+        message: `Script execution error: ${e.message}`,
+        details: e.stack
+      };
+    }
+  }
+
+  /**
+   * Run a simulation to predict compliance with a standard
+   * @param {string} standardId - Standard ID
+   * @param {string} input - Input to test (e.g. commit message)
+   * @returns {Promise<Object>} Simulation result
+   */
+  async simulate(standardId, input) {
+    const standardFile = this.findStandardFile(standardId);
+    if (!standardFile) {
+      return { success: false, message: `Standard '${standardId}' not found.` };
+    }
+
+    let standardConfig;
+    try {
+      standardConfig = yaml.load(fs.readFileSync(standardFile, 'utf-8'));
+    } catch (e) {
+      return { success: false, message: `Failed to parse standard: ${e.message}` };
+    }
+
+    if (!standardConfig.physical_spec || !standardConfig.physical_spec.simulator) {
+      return { 
+        success: false, 
+        message: `Standard '${standardId}' does not support simulation (no 'simulator' spec defined).` 
+      };
+    }
+
+    const { command } = standardConfig.physical_spec.simulator;
+    
+    // Sanitization: Escape double quotes to prevent breaking the echo command
+    // This is a basic implementation. For production, consider using spawn with stdin stream.
+    const sanitizedInput = input.replace(/"/g, '\\"');
+    const finalCommand = command.replace('{input}', sanitizedInput);
+
+    try {
+      const { stdout } = await execAsync(finalCommand, { cwd: this.projectPath });
+      return {
+        success: true,
+        message: 'Simulation passed',
+        details: stdout.trim()
+      };
+    } catch (e) {
+      return {
+        success: false,
+        message: 'Simulation failed',
+        details: e.message + (e.stdout ? `\nOutput: ${e.stdout}` : '')
+      };
+    }
+  }
+}