universal-dev-standards 3.5.0-beta.11 → 3.5.0-beta.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "universal-dev-standards",
-  "version": "3.5.0-beta.11",
+  "version": "3.5.0-beta.12",
   "description": "CLI tool for adopting Universal Development Standards",
   "keywords": [
     "documentation",

package/src/utils/conversion-rules.js

@@ -0,0 +1,232 @@
+/**
+ * Conversion Rules for Markdown to AI-YAML
+ *
+ * Defines mappings, naming conventions, and transformation rules
+ * for converting core standards to AI-optimized format.
+ */
+
+/**
+ * Standard ID mappings
+ * Maps source filename (without .md) to target YAML id
+ */
+export const STANDARD_ID_MAPPING = {
+  'commit-message-guide': 'commit-message',
+  'changelog-standards': 'changelog',
+  'code-review-checklist': 'code-review',
+  'testing-standards': 'testing',
+  'git-workflow': 'git-workflow',
+  'documentation-structure': 'documentation',
+  'checkin-standards': 'checkin',
+  'anti-hallucination': 'anti-hallucination',
+  'versioning': 'versioning',
+  'test-driven-development': 'tdd',
+  'spec-driven-development': 'sdd',
+  'test-completeness-dimensions': 'test-completeness',
+  'logging-standards': 'logging',
+  'error-code-standards': 'error-code',
+  'refactoring-standards': 'refactoring',
+  'graceful-failure': 'graceful-failure',
+  'release-workflow': 'release-workflow'
+};
+
+/**
+ * Section name mappings
+ * Maps Markdown section headers to YAML keys
+ */
+export const SECTION_MAPPINGS = {
+  'Purpose': 'meta.description',
+  'Basic Format': 'format',
+  'Type Classification': 'types',
+  'Scope Guidelines': 'scopes',
+  'Subject Line': 'subject',
+  'Body': 'body',
+  'Footer': 'footer',
+  'Complete Examples': 'examples',
+  'Anti-Patterns': 'anti_patterns',
+  'Automation and Tooling': 'tooling',
+  'Project Configuration Template': 'configuration',
+  'Testing Pyramid': 'pyramid',
+  'Test Categories': 'categories',
+  'Commit Types': 'types',
+  'Branch Naming': 'branches',
+  'Merge Strategy': 'merge_strategy',
+  'Quick Reference': 'quick_reference'
+};
+
+/**
+ * Priority inference patterns
+ * Maps text patterns to priority levels
+ */
+export const PRIORITY_PATTERNS = [
+  { pattern: /\b(MUST|CRITICAL|REQUIRED|ALWAYS)\b/i, priority: 'required' },
+  { pattern: /\b(SHOULD|RECOMMENDED|PREFER)\b/i, priority: 'recommended' },
+  { pattern: /\b(MAY|OPTIONAL|CONSIDER)\b/i, priority: 'optional' },
+  { pattern: /\b(NEVER|MUST NOT|DO NOT)\b/i, priority: 'required' }
+];
+
+/**
+ * Infer priority from text content
+ * @param {string} text - Text to analyze
+ * @returns {string} Priority level (required, recommended, optional)
+ */
+export function inferPriority(text) {
+  for (const { pattern, priority } of PRIORITY_PATTERNS) {
+    if (pattern.test(text)) {
+      return priority;
+    }
+  }
+  return 'recommended'; // Default
+}
+
+/**
+ * Trigger patterns by section type
+ */
+export const TRIGGER_MAPPINGS = {
+  'commit-message': 'writing commit message',
+  'testing': 'writing tests',
+  'code-review': 'reviewing code',
+  'git-workflow': 'managing branches',
+  'documentation': 'writing documentation',
+  'changelog': 'updating changelog',
+  'versioning': 'determining version number',
+  'checkin': 'committing code',
+  'anti-hallucination': 'collaborating with AI',
+  'tdd': 'developing with TDD',
+  'sdd': 'developing with specs',
+  'logging': 'adding logging',
+  'error-code': 'defining error codes',
+  'refactoring': 'refactoring code',
+  'graceful-failure': 'handling failures'
+};
+
+/**
+ * Get trigger text for a standard
+ * @param {string} standardId - Standard identifier
+ * @returns {string} Trigger description
+ */
+export function getTrigger(standardId) {
+  return TRIGGER_MAPPINGS[standardId] || 'applying this standard';
+}
+
+/**
+ * Sections to skip during conversion
+ * These are metadata sections that don't need YAML representation
+ */
+export const SKIP_SECTIONS = [
+  'Version History',
+  'References',
+  'License',
+  'Related Standards'
+];
+
+/**
+ * Check if a section should be skipped
+ * @param {string} sectionName - Section name
+ * @returns {boolean} Whether to skip
+ */
+export function shouldSkipSection(sectionName) {
+  return SKIP_SECTIONS.some(skip =>
+    sectionName.toLowerCase().includes(skip.toLowerCase())
+  );
+}
+
+/**
+ * Validator patterns for common rules
+ */
+export const VALIDATORS = {
+  'commit-subject': '^.{1,72}$',
+  'scope': '^[a-z][a-z0-9-]*$',
+  'version': '^\\d+\\.\\d+\\.\\d+(-[a-zA-Z0-9.]+)?$',
+  'branch-name': '^(feature|fix|docs|chore|hotfix)/[a-z0-9-]+$',
+  'commit-type': '^(feat|fix|docs|style|refactor|test|perf|build|ci|chore|revert|security)$'
+};
+
+/**
+ * Get validator for a rule type
+ * @param {string} ruleType - Type of rule
+ * @returns {string|null} Regex validator or null
+ */
+export function getValidator(ruleType) {
+  return VALIDATORS[ruleType] || null;
+}
+
+/**
+ * Locale configurations
+ */
+export const LOCALE_CONFIG = {
+  'zh-TW': {
+    name: 'Traditional Chinese',
+    direction: 'ltr',
+    coreDir: 'locales/zh-TW/core',
+    aiDir: 'locales/zh-TW/ai/standards'
+  },
+  'zh-CN': {
+    name: 'Simplified Chinese',
+    direction: 'ltr',
+    coreDir: 'locales/zh-CN/core',
+    aiDir: 'locales/zh-CN/ai/standards'
+  }
+};
+
+/**
+ * Get locale configuration
+ * @param {string} locale - Locale code
+ * @returns {Object|null} Locale config or null
+ */
+export function getLocaleConfig(locale) {
+  return LOCALE_CONFIG[locale] || null;
+}
+
+/**
+ * Get all supported locales
+ * @returns {string[]} Array of locale codes
+ */
+export function getSupportedLocales() {
+  return Object.keys(LOCALE_CONFIG);
+}
+
+/**
+ * Output path mappings
+ * Maps source patterns to output directories
+ */
+export const OUTPUT_PATHS = {
+  'core': 'ai/standards',
+  'locales/zh-TW/core': 'locales/zh-TW/ai/standards',
+  'locales/zh-CN/core': 'locales/zh-CN/ai/standards'
+};
+
+/**
+ * Get output directory for a source path
+ * @param {string} sourcePath - Source file path
+ * @returns {string} Output directory
+ */
+export function getOutputDir(sourcePath) {
+  // Check longer patterns first (locales before core)
+  // Sort by pattern length descending to ensure more specific matches first
+  const sortedEntries = Object.entries(OUTPUT_PATHS)
+    .sort((a, b) => b[0].length - a[0].length);
+
+  for (const [pattern, outputDir] of sortedEntries) {
+    if (sourcePath.includes(pattern)) {
+      return outputDir;
+    }
+  }
+  return 'ai/standards';
+}
+
+/**
+ * Generate output filename from source filename
+ * @param {string} sourceFilename - Source .md filename
+ * @returns {string} Output .ai.yaml filename
+ */
+export function getOutputFilename(sourceFilename) {
+  // Get the base name without .md
+  let baseName = sourceFilename.replace(/\.md$/, '');
+
+  // Map to standard ID if available
+  if (STANDARD_ID_MAPPING[baseName]) {
+    baseName = STANDARD_ID_MAPPING[baseName];
+  }
+
+  return `${baseName}.ai.yaml`;
+}

package/src/utils/detector.js

@@ -117,6 +117,8 @@ export function detectFramework(projectPath) {
  * @returns {Object} Detected AI tools
  */
 export function detectAITools(projectPath) {
+  const hasAgentsMd = existsSync(join(projectPath, 'AGENTS.md'));
+
   const detected = {
     cursor: existsSync(join(projectPath, '.cursorrules')),
     windsurf: existsSync(join(projectPath, '.windsurfrules')),
@@ -124,7 +126,10 @@ export function detectAITools(projectPath) {
     copilot: existsSync(join(projectPath, '.github', 'copilot-instructions.md')),
     claudeCode: existsSync(join(projectPath, '.claude')) ||
                 existsSync(join(projectPath, 'CLAUDE.md')),
-    antigravity: existsSync(join(projectPath, 'INSTRUCTIONS.md'))
+    antigravity: existsSync(join(projectPath, 'INSTRUCTIONS.md')),
+    codex: hasAgentsMd,
+    opencode: hasAgentsMd,
+    geminiCli: existsSync(join(projectPath, 'GEMINI.md'))
   };
 
   return detected;

package/src/utils/md-parser.js

@@ -0,0 +1,429 @@
+/**
+ * Markdown Parser for AI-YAML Conversion
+ *
+ * Parses core standard Markdown files into a structured representation
+ * that can be converted to AI-optimized YAML format.
+ */
+
+/**
+ * Parse Markdown content into structured representation
+ * @param {string} content - Raw Markdown content
+ * @returns {Object} Parsed structure
+ */
+export function parseMarkdown(content) {
+  const lines = content.split('\n');
+
+  return {
+    metadata: extractMetadata(lines),
+    purpose: extractPurpose(content),
+    sections: extractSections(content),
+    tables: extractTables(content),
+    codeBlocks: extractCodeBlocks(content),
+    decisionPoints: extractDecisionPoints(content),
+    relatedStandards: extractRelatedStandards(content),
+    versionHistory: extractVersionHistory(content)
+  };
+}
+
+/**
+ * Extract metadata from the header lines
+ * Format expected:
+ *   Line 1: # Title
+ *   Line 3: > **Language**: English | [繁體中文](...)
+ *   Line 5: **Version**: X.Y.Z
+ *   Line 6: **Last Updated**: YYYY-MM-DD
+ *   Line 7: **Applicability**: ...
+ */
+function extractMetadata(lines) {
+  const metadata = {
+    title: '',
+    version: '',
+    updated: '',
+    applicability: '',
+    languageLink: null
+  };
+
+  for (let i = 0; i < Math.min(lines.length, 15); i++) {
+    const line = lines[i];
+
+    // Title: # Title
+    if (line.startsWith('# ') && !metadata.title) {
+      metadata.title = line.substring(2).trim();
+    }
+
+    // Language link: > **Language**: English | [繁體中文](...)
+    const langMatch = line.match(/>\s*\*\*Language\*\*:\s*(.+)/);
+    if (langMatch) {
+      const linkMatch = langMatch[1].match(/\[(.+?)\]\((.+?)\)/);
+      if (linkMatch) {
+        metadata.languageLink = {
+          text: linkMatch[1],
+          path: linkMatch[2]
+        };
+      }
+    }
+
+    // Version: **Version**: X.Y.Z
+    const versionMatch = line.match(/\*\*Version\*\*:\s*(.+)/);
+    if (versionMatch) {
+      metadata.version = versionMatch[1].trim();
+    }
+
+    // Last Updated: **Last Updated**: YYYY-MM-DD
+    const updatedMatch = line.match(/\*\*Last Updated\*\*:\s*(.+)/);
+    if (updatedMatch) {
+      metadata.updated = updatedMatch[1].trim();
+    }
+
+    // Applicability: **Applicability**: ...
+    const applicabilityMatch = line.match(/\*\*Applicability\*\*:\s*(.+)/);
+    if (applicabilityMatch) {
+      metadata.applicability = applicabilityMatch[1].trim();
+    }
+  }
+
+  return metadata;
+}
+
+/**
+ * Extract the Purpose section content
+ */
+function extractPurpose(content) {
+  const purposeMatch = content.match(/## Purpose\s*\n+([\s\S]*?)(?=\n---|\n## )/);
+  if (purposeMatch) {
+    return purposeMatch[1].trim();
+  }
+  return '';
+}
+
+/**
+ * Extract all ## sections with their content
+ */
+function extractSections(content) {
+  const sections = [];
+  const sectionRegex = /^## (.+)$/gm;
+  const matches = [...content.matchAll(sectionRegex)];
+
+  for (let i = 0; i < matches.length; i++) {
+    const match = matches[i];
+    const name = match[1].trim();
+    const startIdx = match.index + match[0].length;
+    const endIdx = matches[i + 1] ? matches[i + 1].index : content.length;
+
+    let sectionContent = content.substring(startIdx, endIdx).trim();
+
+    // Remove leading --- if present
+    sectionContent = sectionContent.replace(/^---\s*/, '').trim();
+
+    // Classify section type
+    const type = classifySectionType(name, sectionContent);
+
+    sections.push({
+      name,
+      content: sectionContent,
+      type,
+      subsections: extractSubsections(sectionContent)
+    });
+  }
+
+  return sections;
+}
+
+/**
+ * Extract ### subsections from section content
+ */
+function extractSubsections(content) {
+  const subsections = [];
+  const subRegex = /^### (.+)$/gm;
+  const matches = [...content.matchAll(subRegex)];
+
+  for (let i = 0; i < matches.length; i++) {
+    const match = matches[i];
+    const name = match[1].trim();
+    const startIdx = match.index + match[0].length;
+    const endIdx = matches[i + 1] ? matches[i + 1].index : content.length;
+
+    subsections.push({
+      name,
+      content: content.substring(startIdx, endIdx).trim()
+    });
+  }
+
+  return subsections;
+}
+
+/**
+ * Classify section type based on name and content
+ */
+function classifySectionType(name, content) {
+  const nameLower = name.toLowerCase();
+
+  if (nameLower === 'purpose') return 'purpose';
+  if (nameLower.includes('version history')) return 'version-history';
+  if (nameLower.includes('related standards')) return 'related-standards';
+  if (nameLower.includes('references')) return 'references';
+  if (nameLower === 'license') return 'license';
+  if (nameLower.includes('anti-pattern')) return 'anti-patterns';
+  if (nameLower.includes('example')) return 'examples';
+  if (nameLower.includes('configuration') || nameLower.includes('template')) return 'configuration';
+
+  // Check content for table presence
+  if (content.includes('| ') && content.includes(' |')) {
+    return 'table-content';
+  }
+
+  // Check for decision points
+  if (content.includes('PROJECT MUST CHOOSE') || content.includes('MUST CHOOSE ONE')) {
+    return 'decision-point';
+  }
+
+  return 'content';
+}
+
+/**
+ * Extract all tables from content
+ */
+function extractTables(content) {
+  const tables = [];
+  // Match tables with header, separator, and rows
+  const tableRegex = /(?:^|\n)((?:\|[^\n]+\|\n)+)/g;
+  const matches = [...content.matchAll(tableRegex)];
+
+  for (const match of matches) {
+    const tableContent = match[1].trim();
+    const lines = tableContent.split('\n').filter(l => l.trim());
+
+    if (lines.length < 2) continue;
+
+    // Parse header
+    const headerLine = lines[0];
+    const headers = parseTableRow(headerLine);
+
+    // Skip separator line (|---|---|)
+    const dataStartIdx = lines[1].includes('---') ? 2 : 1;
+
+    // Parse data rows
+    const rows = [];
+    for (let i = dataStartIdx; i < lines.length; i++) {
+      const row = parseTableRow(lines[i]);
+      if (row.length > 0) {
+        rows.push(row);
+      }
+    }
+
+    // Try to find table context (previous heading or text)
+    const tableStart = match.index;
+    const precedingContent = content.substring(Math.max(0, tableStart - 200), tableStart);
+    const contextMatch = precedingContent.match(/###?\s+([^\n]+)\s*$/);
+    const context = contextMatch ? contextMatch[1].trim() : '';
+
+    tables.push({
+      headers,
+      rows,
+      context,
+      raw: tableContent
+    });
+  }
+
+  return tables;
+}
+
+/**
+ * Parse a single table row
+ */
+function parseTableRow(line) {
+  return line
+    .split('|')
+    .map(cell => cell.trim())
+    .filter(cell => cell && !cell.match(/^-+$/));
+}
+
+/**
+ * Extract code blocks from content
+ */
+function extractCodeBlocks(content) {
+  const codeBlocks = [];
+  const codeRegex = /```(\w*)\n([\s\S]*?)```/g;
+  const matches = [...content.matchAll(codeRegex)];
+
+  for (const match of matches) {
+    const lang = match[1] || 'text';
+    const code = match[2].trim();
+
+    // Find context (preceding text)
+    const blockStart = match.index;
+    const precedingContent = content.substring(Math.max(0, blockStart - 300), blockStart);
+    const contextMatch = precedingContent.match(/(?:^|\n)([^\n]+)\s*$/);
+    const context = contextMatch ? contextMatch[1].trim() : '';
+
+    codeBlocks.push({
+      lang,
+      content: code,
+      context
+    });
+  }
+
+  return codeBlocks;
+}
+
+/**
+ * Extract decision points (PROJECT MUST CHOOSE patterns)
+ */
+function extractDecisionPoints(content) {
+  const decisions = [];
+
+  // Pattern: PROJECT MUST CHOOSE ONE
+  const chooseOneRegex = /PROJECT MUST CHOOSE ONE\s+([A-Z]+)\s*/gi;
+  const matches = [...content.matchAll(chooseOneRegex)];
+
+  for (const match of matches) {
+    const topic = match[1].toLowerCase();
+    decisions.push({
+      type: 'choose-one',
+      topic,
+      context: extractContextAround(content, match.index)
+    });
+  }
+
+  // Pattern: ### Option A: / ### Option B: / ### Option C:
+  const optionSections = content.match(/### Option [A-C]:?\s+([^\n]+)/g);
+  if (optionSections && optionSections.length > 0) {
+    const options = optionSections.map(opt => {
+      const match = opt.match(/### Option ([A-C]):?\s+(.+)/);
+      return match ? { id: match[1], label: match[2].trim() } : null;
+    }).filter(Boolean);
+
+    if (options.length > 0) {
+      decisions.push({
+        type: 'options',
+        options
+      });
+    }
+  }
+
+  return decisions;
+}
+
+/**
+ * Extract context around a match position
+ */
+function extractContextAround(content, position) {
+  const start = Math.max(0, position - 100);
+  const end = Math.min(content.length, position + 200);
+  return content.substring(start, end).trim();
+}
+
+/**
+ * Extract Related Standards section
+ */
+function extractRelatedStandards(content) {
+  const relatedMatch = content.match(/## Related Standards\s*\n+([\s\S]*?)(?=\n---|\n## )/);
+  if (!relatedMatch) return [];
+
+  const links = [];
+  const linkRegex = /\[(.+?)\]\((.+?)\)/g;
+  const matches = [...relatedMatch[1].matchAll(linkRegex)];
+
+  for (const match of matches) {
+    links.push({
+      name: match[1],
+      path: match[2]
+    });
+  }
+
+  return links;
+}
+
+/**
+ * Extract Version History table
+ */
+function extractVersionHistory(content) {
+  const historyMatch = content.match(/## Version History\s*\n+([\s\S]*?)(?=\n---|\n## |$)/);
+  if (!historyMatch) return [];
+
+  const tableContent = historyMatch[1];
+  const lines = tableContent.split('\n').filter(l => l.includes('|'));
+
+  if (lines.length < 3) return []; // Need header, separator, at least one row
+
+  const history = [];
+  // Skip header and separator
+  for (let i = 2; i < lines.length; i++) {
+    const row = parseTableRow(lines[i]);
+    if (row.length >= 3) {
+      history.push({
+        version: row[0],
+        date: row[1],
+        changes: row[2]
+      });
+    }
+  }
+
+  return history;
+}
+
+/**
+ * Extract rules from content based on imperative patterns
+ * Finds statements with MUST, SHOULD, etc.
+ */
+export function extractRules(content) {
+  const rules = [];
+
+  // Pattern: statements containing MUST, SHOULD, CRITICAL, IMPORTANT
+  const rulePatterns = [
+    { regex: /\*\*CRITICAL\*\*:?\s*([^.\n]+)/gi, priority: 'required' },
+    { regex: /\*\*IMPORTANT\*\*:?\s*([^.\n]+)/gi, priority: 'required' },
+    { regex: /(?:^|\n)\s*-\s*MUST\s+([^.\n]+)/gi, priority: 'required' },
+    { regex: /(?:^|\n)\s*-\s*SHOULD\s+([^.\n]+)/gi, priority: 'recommended' },
+    { regex: /(?:^|\n)\s*-\s*Always\s+([^.\n]+)/gi, priority: 'required' },
+    { regex: /(?:^|\n)\s*-\s*Never\s+([^.\n]+)/gi, priority: 'required' }
+  ];
+
+  for (const pattern of rulePatterns) {
+    const matches = [...content.matchAll(pattern.regex)];
+    for (const match of matches) {
+      const instruction = match[1].trim();
+      if (instruction.length > 10) { // Filter out too short matches
+        rules.push({
+          instruction,
+          priority: pattern.priority,
+          source: match[0].trim().substring(0, 50)
+        });
+      }
+    }
+  }
+
+  return rules;
+}
+
+/**
+ * Generate a kebab-case ID from filename or title
+ */
+export function generateId(filename) {
+  // Remove .md extension
+  let id = filename.replace(/\.md$/, '');
+
+  // Remove common suffixes
+  id = id.replace(/-?(guide|standards|standard|checklist)$/i, '');
+
+  // Convert to kebab-case
+  id = id
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+
+  return id;
+}
+
+/**
+ * Infer the source path for a standard
+ */
+export function inferSourcePath(filename, locale = null) {
+  const cleanName = filename.replace(/\.md$/, '.md');
+
+  if (locale) {
+    return `locales/${locale}/core/${cleanName}`;
+  }
+
+  return `core/${cleanName}`;
+}

package/src/utils/yaml-generator.js

@@ -0,0 +1,575 @@
+/**
+ * YAML Generator for AI-YAML Conversion
+ *
+ * Generates AI-optimized YAML from parsed Markdown structure.
+ */
+
+import { SECTION_MAPPINGS, STANDARD_ID_MAPPING } from './conversion-rules.js';
+
+/**
+ * Generate AI-YAML structure from parsed Markdown
+ * @param {Object} parsed - Parsed Markdown structure from md-parser
+ * @param {Object} options - Generation options
+ * @returns {Object} AI-YAML structure
+ */
+export function generateAiYaml(parsed, options = {}) {
+  const { filename = '', locale = null } = options;
+
+  // Generate ID
+  const id = generateStandardId(filename, parsed.metadata.title);
+
+  // Build YAML structure
+  const yaml = {
+    id,
+    meta: {
+      version: parsed.metadata.version || '1.0.0',
+      updated: parsed.metadata.updated || new Date().toISOString().split('T')[0],
+      source: inferSourcePath(filename, locale),
+      description: parsed.purpose || parsed.metadata.title || ''
+    }
+  };
+
+  // Add language if locale specified
+  if (locale) {
+    yaml.meta.language = locale;
+  }
+
+  // Process sections to extract structured content
+  const structuredContent = processStructuredContent(parsed);
+
+  // Merge structured content
+  Object.assign(yaml, structuredContent);
+
+  // Generate rules from content
+  const rules = generateRules(parsed);
+  if (rules.length > 0) {
+    yaml.rules = rules;
+  }
+
+  // Generate quick reference from tables
+  const quickRef = generateQuickReference(parsed);
+  if (Object.keys(quickRef).length > 0) {
+    yaml.quick_reference = quickRef;
+  }
+
+  // Process decision points into options structure
+  const decisionsAndOptions = processDecisions(parsed);
+  if (decisionsAndOptions.decision) {
+    yaml.decision = decisionsAndOptions.decision;
+  }
+  if (decisionsAndOptions.options) {
+    yaml.options = decisionsAndOptions.options;
+  }
+
+  return yaml;
+}
+
+/**
+ * Generate standard ID from filename or title
+ */
+function generateStandardId(filename, _title) {
+  // Check mapping first
+  const cleanName = filename.replace(/\.md$/, '');
+  if (STANDARD_ID_MAPPING[cleanName]) {
+    return STANDARD_ID_MAPPING[cleanName];
+  }
+
+  // Generate from filename (title reserved for future use)
+  let id = cleanName
+    .toLowerCase()
+    .replace(/-?(guide|standards|standard|checklist)$/i, '')
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+
+  return id || 'unknown';
+}
+
+/**
+ * Infer source path
+ */
+function inferSourcePath(filename, locale) {
+  const cleanName = filename || 'unknown.md';
+
+  if (locale) {
+    return `locales/${locale}/core/${cleanName}`;
+  }
+
+  return `core/${cleanName}`;
+}
+
+/**
+ * Process sections into structured content
+ */
+function processStructuredContent(parsed) {
+  const content = {};
+
+  for (const section of parsed.sections) {
+    const sectionKey = getSectionKey(section.name);
+
+    // Skip metadata sections
+    if (['version-history', 'references', 'license', 'related-standards'].includes(section.type)) {
+      continue;
+    }
+
+    // Skip purpose (already in meta.description)
+    if (section.type === 'purpose') {
+      continue;
+    }
+
+    // Process based on section type
+    if (section.type === 'table-content' && section.subsections.length === 0) {
+      // Simple table section - will be in quick_reference
+      continue;
+    }
+
+    // Handle sections with subsections
+    if (section.subsections.length > 0) {
+      const sectionData = {};
+
+      for (const sub of section.subsections) {
+        const subKey = toKebabCase(sub.name);
+        sectionData[subKey] = extractSubsectionContent(sub);
+      }
+
+      if (Object.keys(sectionData).length > 0) {
+        content[sectionKey] = sectionData;
+      }
+    }
+  }
+
+  return content;
+}
+
+/**
+ * Get YAML key for a section
+ */
+function getSectionKey(sectionName) {
+  // Check custom mappings
+  if (SECTION_MAPPINGS[sectionName]) {
+    return SECTION_MAPPINGS[sectionName];
+  }
+
+  return toKebabCase(sectionName);
+}
+
+/**
+ * Convert string to kebab-case
+ */
+function toKebabCase(str) {
+  return str
+    .toLowerCase()
+    .replace(/[^a-z0-9\u4e00-\u9fff]+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+/**
+ * Extract content from a subsection
+ */
+function extractSubsectionContent(subsection) {
+  const content = subsection.content;
+
+  // Check if it's primarily a list
+  const listItems = content.match(/^[-*]\s+(.+)$/gm);
+  if (listItems && listItems.length > 2) {
+    return listItems.map(item => item.replace(/^[-*]\s+/, '').trim());
+  }
+
+  // Check if it's a code block
+  const codeMatch = content.match(/```\w*\n([\s\S]*?)```/);
+  if (codeMatch) {
+    return codeMatch[1].trim();
+  }
+
+  // Return as text (truncated if too long)
+  const text = content.replace(/\n+/g, ' ').trim();
+  return text.length > 200 ? text.substring(0, 200) + '...' : text;
+}
+
+/**
+ * Generate rules from parsed content
+ */
+function generateRules(parsed) {
+  const rules = [];
+  let ruleIndex = 1;
+
+  // Extract rules from sections with imperative language
+  for (const section of parsed.sections) {
+    const sectionRules = extractRulesFromSection(section, ruleIndex);
+    rules.push(...sectionRules);
+    ruleIndex += sectionRules.length;
+  }
+
+  // Deduplicate similar rules
+  const uniqueRules = deduplicateRules(rules);
+
+  return uniqueRules.slice(0, 15); // Limit to 15 rules
+}
+
+/**
+ * Extract rules from a section
+ */
+function extractRulesFromSection(section, startIndex) {
+  const rules = [];
+  const content = section.content;
+
+  // Pattern: bullet points with action words
+  const bulletPatterns = [
+    { regex: /^[-*]\s+(?:\*\*)?([A-Z][^:.\n]{10,60})(?:\*\*)?[:.]/gm, priority: 'required' },
+    { regex: /^[-*]\s+Must\s+([^.\n]{10,60})/gim, priority: 'required' },
+    { regex: /^[-*]\s+Should\s+([^.\n]{10,60})/gim, priority: 'recommended' },
+    { regex: /^[-*]\s+Always\s+([^.\n]{10,60})/gim, priority: 'required' },
+    { regex: /^[-*]\s+Never\s+([^.\n]{10,60})/gim, priority: 'required' }
+  ];
+
+  for (const pattern of bulletPatterns) {
+    const matches = [...content.matchAll(pattern.regex)];
+    for (const match of matches) {
+      const instruction = match[1].trim();
+      if (instruction.length > 10 && instruction.length < 100) {
+        const ruleId = `${toKebabCase(section.name)}-${startIndex + rules.length}`;
+        rules.push({
+          id: ruleId,
+          trigger: inferTrigger(section.name),
+          instruction: cleanInstruction(instruction),
+          priority: pattern.priority
+        });
+      }
+    }
+  }
+
+  return rules;
+}
+
+/**
+ * Infer trigger from section name
+ */
+function inferTrigger(sectionName) {
+  const nameLower = sectionName.toLowerCase();
+
+  if (nameLower.includes('commit')) return 'writing commit message';
+  if (nameLower.includes('scope')) return 'specifying scope';
+  if (nameLower.includes('subject')) return 'writing subject line';
+  if (nameLower.includes('body')) return 'writing commit body';
+  if (nameLower.includes('footer')) return 'adding footer';
+  if (nameLower.includes('type')) return 'choosing type';
+  if (nameLower.includes('format')) return 'formatting';
+  if (nameLower.includes('test')) return 'writing tests';
+  if (nameLower.includes('review')) return 'reviewing code';
+  if (nameLower.includes('branch')) return 'working with branches';
+
+  return 'applying this standard';
+}
+
+/**
+ * Clean instruction text
+ */
+function cleanInstruction(text) {
+  return text
+    .replace(/\*\*/g, '')
+    .replace(/`/g, '')
+    .replace(/\s+/g, ' ')
+    .trim();
+}
+
+/**
+ * Deduplicate similar rules
+ */
+function deduplicateRules(rules) {
+  const seen = new Set();
+  const unique = [];
+
+  for (const rule of rules) {
+    const normalized = rule.instruction.toLowerCase().substring(0, 30);
+    if (!seen.has(normalized)) {
+      seen.add(normalized);
+      unique.push(rule);
+    }
+  }
+
+  return unique;
+}
+
+/**
+ * Generate quick reference from tables
+ */
+function generateQuickReference(parsed) {
+  const quickRef = {};
+
+  for (const table of parsed.tables) {
+    if (table.headers.length < 2 || table.rows.length < 1) {
+      continue;
+    }
+
+    // Generate table key from context or headers
+    const tableKey = generateTableKey(table);
+
+    quickRef[tableKey] = {
+      columns: table.headers,
+      rows: table.rows
+    };
+  }
+
+  return quickRef;
+}
+
+/**
+ * Generate a key for a table
+ */
+function generateTableKey(table) {
+  // Use context if available
+  if (table.context) {
+    return toKebabCase(table.context);
+  }
+
+  // Use first header
+  if (table.headers[0]) {
+    return toKebabCase(table.headers[0]) + '-table';
+  }
+
+  return 'reference-table';
+}
+
+/**
+ * Process decision points into options structure
+ */
+function processDecisions(parsed) {
+  const result = {};
+
+  if (parsed.decisionPoints.length === 0) {
+    return result;
+  }
+
+  // Find option sections
+  const optionDecision = parsed.decisionPoints.find(d => d.type === 'options');
+  if (optionDecision) {
+    result.decision = {
+      question: 'Which option best fits your project?',
+      matrix: optionDecision.options.map(opt => ({
+        answer: opt.label,
+        select: toKebabCase(opt.label)
+      }))
+    };
+
+    // Generate options structure
+    const optionCategory = inferOptionCategory(parsed.metadata.title);
+    result.options = {
+      [optionCategory]: {
+        default: toKebabCase(optionDecision.options[0]?.label || 'default'),
+        choices: optionDecision.options.map(opt => ({
+          id: toKebabCase(opt.label),
+          file: `options/${optionCategory}/${toKebabCase(opt.label)}.ai.yaml`
+        }))
+      }
+    };
+  }
+
+  return result;
+}
+
+/**
+ * Infer option category from title
+ */
+function inferOptionCategory(title) {
+  const titleLower = title?.toLowerCase() || '';
+
+  if (titleLower.includes('commit')) return 'commit_language';
+  if (titleLower.includes('test')) return 'testing_approach';
+  if (titleLower.includes('git')) return 'git_workflow';
+  if (titleLower.includes('changelog')) return 'changelog_format';
+  if (titleLower.includes('review')) return 'review_style';
+
+  return 'default_option';
+}
+
+/**
+ * Convert YAML object to formatted string
+ * @param {Object} obj - YAML object
+ * @returns {string} Formatted YAML string
+ */
+export function toYamlString(obj) {
+  const lines = [];
+
+  // Add header comment
+  if (obj.meta?.source) {
+    const title = obj.id || 'Standard';
+    lines.push(`# ${title.charAt(0).toUpperCase() + title.slice(1).replace(/-/g, ' ')} - AI Optimized`);
+    lines.push(`# Source: ${obj.meta.source}`);
+    lines.push('');
+  }
+
+  // Serialize object
+  serializeObject(obj, lines, 0);
+
+  return lines.join('\n');
+}
+
+/**
+ * Serialize a YAML value to string
+ */
+function serializeScalar(value, indent) {
+  if (value === null || value === undefined) {
+    return 'null';
+  }
+
+  if (typeof value === 'boolean') {
+    return value ? 'true' : 'false';
+  }
+
+  if (typeof value === 'number') {
+    return String(value);
+  }
+
+  if (typeof value === 'string') {
+    // Check if multiline
+    if (value.includes('\n')) {
+      const prefix = '  '.repeat(indent + 1);
+      return '|\n' + value.split('\n').map(line => prefix + line).join('\n');
+    }
+
+    // Check if needs quoting
+    if (value === '' ||
+        value.match(/^[\s]|[\s]$/) ||
+        value.match(/^[#&*!|>'"%@`]/) ||
+        value.match(/[:#{}[\],&*?|<>=!%@`]/) ||
+        value.match(/^(true|false|null|yes|no|on|off)$/i) ||
+        value.match(/^\d/)) {
+      return `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+    }
+
+    return value;
+  }
+
+  return String(value);
+}
+
+/**
+ * Serialize an object to YAML lines
+ */
+function serializeObject(obj, lines, indent) {
+  const prefix = '  '.repeat(indent);
+
+  for (const [key, value] of Object.entries(obj)) {
+    if (value === null || value === undefined) {
+      continue;
+    }
+
+    if (Array.isArray(value)) {
+      if (value.length === 0) {
+        lines.push(`${prefix}${key}: []`);
+      } else if (isSimpleArray(value)) {
+        // Inline simple arrays
+        const items = value.map(v => serializeScalar(v, indent));
+        lines.push(`${prefix}${key}: [${items.join(', ')}]`);
+      } else {
+        // Block array
+        lines.push(`${prefix}${key}:`);
+        for (const item of value) {
+          serializeArrayItem(item, lines, indent + 1);
+        }
+      }
+    } else if (typeof value === 'object') {
+      lines.push(`${prefix}${key}:`);
+      serializeObject(value, lines, indent + 1);
+    } else {
+      lines.push(`${prefix}${key}: ${serializeScalar(value, indent)}`);
+    }
+  }
+}
+
+/**
+ * Serialize an array item
+ */
+function serializeArrayItem(item, lines, indent) {
+  const prefix = '  '.repeat(indent);
+
+  if (typeof item === 'object' && item !== null && !Array.isArray(item)) {
+    const entries = Object.entries(item);
+    if (entries.length === 0) {
+      lines.push(`${prefix}- {}`);
+      return;
+    }
+
+    // First key on same line as dash
+    const [firstKey, firstVal] = entries[0];
+    if (typeof firstVal === 'object' && firstVal !== null) {
+      lines.push(`${prefix}- ${firstKey}:`);
+      if (Array.isArray(firstVal)) {
+        for (const subItem of firstVal) {
+          serializeArrayItem(subItem, lines, indent + 2);
+        }
+      } else {
+        serializeObject(firstVal, lines, indent + 2);
+      }
+    } else {
+      lines.push(`${prefix}- ${firstKey}: ${serializeScalar(firstVal, indent)}`);
+    }
+
+    // Rest of keys indented
+    for (let i = 1; i < entries.length; i++) {
+      const [key, val] = entries[i];
+      if (typeof val === 'object' && val !== null) {
+        lines.push(`${prefix}  ${key}:`);
+        if (Array.isArray(val)) {
+          for (const subItem of val) {
+            serializeArrayItem(subItem, lines, indent + 2);
+          }
+        } else {
+          serializeObject(val, lines, indent + 2);
+        }
+      } else {
+        lines.push(`${prefix}  ${key}: ${serializeScalar(val, indent + 1)}`);
+      }
+    }
+  } else {
+    lines.push(`${prefix}- ${serializeScalar(item, indent)}`);
+  }
+}
+
+/**
+ * Check if array contains only simple values
+ */
+function isSimpleArray(arr) {
+  return arr.length <= 5 && arr.every(v =>
+    (typeof v === 'string' && v.length < 50 && !v.includes('\n')) ||
+    typeof v === 'number' ||
+    typeof v === 'boolean'
+  );
+}
+
+/**
+ * Extract manual sections from existing YAML content
+ * @param {string} content - Existing YAML content
+ * @returns {Object} Extracted sections
+ */
+export function extractManualSections(content) {
+  const result = {
+    hasManualSections: false,
+    manualContent: ''
+  };
+
+  const manualMatch = content.match(/# MANUAL ADDITIONS START\s*([\s\S]*?)# MANUAL ADDITIONS END/);
+  if (manualMatch) {
+    result.hasManualSections = true;
+    result.manualContent = manualMatch[1].trim();
+  }
+
+  return result;
+}
+
+/**
+ * Merge manual sections into generated YAML
+ */
+export function mergeManualSections(generatedYaml, manualContent) {
+  if (!manualContent) {
+    return generatedYaml;
+  }
+
+  // Add markers and manual content at the end
+  return `${generatedYaml}
+
+# MANUAL ADDITIONS START
+# Add custom rules below this line
+${manualContent}
+# MANUAL ADDITIONS END
+`;
+}

package/standards-registry.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
-  "version": "3.5.0-beta.11",
-  "lastUpdated": "2026-01-11",
+  "version": "3.5.0-beta.12",
+  "lastUpdated": "2026-01-12",
   "description": "Standards registry for universal-dev-standards with integrated skills and AI-optimized formats",
   "formats": {
     "ai": {
@@ -48,14 +48,14 @@
     "standards": {
       "name": "universal-dev-standards",
       "url": "https://github.com/AsiaOstrich/universal-dev-standards",
-      "version": "3.5.0-beta.11"
+      "version": "3.5.0-beta.12"
     },
     "skills": {
       "name": "universal-dev-standards",
       "url": "https://github.com/AsiaOstrich/universal-dev-standards",
       "localPath": "skills/claude-code",
       "rawUrl": "https://raw.githubusercontent.com/AsiaOstrich/universal-dev-standards/main/skills/claude-code",
-      "version": "3.5.0-beta.11",
+      "version": "3.5.0-beta.12",
       "note": "Skills are now included in the main repository under skills/"
     }
   },
@@ -588,6 +588,16 @@
       "level": 2,
       "description": "Red-Green-Refactor methodology for TDD workflow"
     },
+    {
+      "id": "refactoring-standards",
+      "name": "Refactoring Standards",
+      "nameZh": "重構標準",
+      "source": "core/refactoring-standards.md",
+      "category": "reference",
+      "skillName": null,
+      "level": 2,
+      "description": "Comprehensive refactoring guidelines covering legacy code strategies, large-scale patterns, database refactoring, metrics, and team collaboration"
+    },
     {
       "id": "csharp-style",
       "name": "C# Style Guide",