aios-core 2.1.4 → 2.1.6

package/.aios-core/development/tasks/validate-structure.md

@@ -1,243 +0,0 @@
-# validate-structure
-
-**Task ID:** validate-structure
-**Version:** 1.0.0
-**Agent:** @architect (Aria)
-**Story:** 6.8 - Source-Tree Guardian
-
----
-
-## Purpose
-
-Validate file placement decisions against AIOS source-tree standards before implementation begins.
-
-**This task is MANDATORY for all stories that create new files.**
-
----
-
-## When to Use
-
-- Before starting implementation of any story
-- When planning new modules or features
-- During architecture review
-- Before PR submission
-
----
-
-## Prerequisites
-
-- Story file exists with implementation plan
-- Source-tree-guardian module installed
-- Access to `docs/architecture/source-tree.md`
-
----
-
-## Execution
-
-### Step 1: List New Files
-
-List all files that will be created in this story:
-
-| File | Purpose | Category |
-|------|---------|----------|
-| {path} | {purpose} | {agent/task/script/test/etc} |
-
-### Step 2: Validate Each File
-
-For each file, run placement validation:
-
-```bash
-npm run validate:structure -- --check "{file_path}"
-```
-
-Or validate all planned files at once:
-
-```bash
-npm run validate:structure -- --files "{glob_pattern}"
-```
-
-### Step 3: Document Decisions
-
-Add the following section to the story file:
-
-```markdown
-## Structure Validation
-
-| File | Validated Location | Approved |
-|------|-------------------|----------|
-| {file} | {location} | ✅/❌ |
-
-**Validated by:** @architect (Aria)
-**Date:** {YYYY-MM-DD}
-**Violations:** {count}
-**Notes:** {any special decisions}
-```
-
-### Step 4: Handle Violations
-
-If violations exist:
-
-1. **Review the violation message** - Understand why the location is flagged
-2. **Propose correct location** - Use suggested location or justify alternative
-3. **Get PO approval** - If deviation from standard is needed
-4. **Document reasoning** - Create ADR if significant deviation
-5. **Update story** - Mark as resolved or approved exception
-
----
-
-## Task Definition (YAML)
-
-```yaml
-task: validateStructure()
-responsável: Aria (Architect)
-responsavel_type: Agente
-atomic_layer: Molecule
-elicit: true
-
-Entrada:
-  - campo: story_files
-    tipo: array
-    origem: Story implementation plan
-    obrigatório: true
-    descrição: List of files to be created/modified
-
-  - campo: story_path
-    tipo: string
-    origem: User input or context
-    obrigatório: true
-    descrição: Path to the story file
-
-Saída:
-  - campo: placement_report
-    tipo: object
-    destino: Story file (## Structure Validation section)
-    persistido: true
-
-  - campo: violations
-    tipo: array
-    destino: Console output
-    persistido: false
-
-Elicitation:
-  - prompt: "What files will be created in this story?"
-    type: list
-    required: true
-    help: "List each file with its full path"
-
-  - prompt: "For each file, what is its purpose?"
-    type: text
-    required: true
-    help: "Brief description of what each file does"
-
-  - prompt: "What category does each file belong to?"
-    type: select
-    options:
-      - agent
-      - task
-      - script
-      - template
-      - checklist
-      - test
-      - documentation
-      - configuration
-      - other
-    required: true
-```
-
----
-
-## Checklist
-
-Use this checklist to ensure complete validation:
-
-- [ ] All new files have been listed
-- [ ] Each file has been validated against source-tree.md
-- [ ] Placement decisions are documented in story
-- [ ] Any violations have been resolved or approved
-- [ ] @architect sign-off is complete
-- [ ] Story "Structure Validation" section is populated
-
----
-
-## CLI Commands Reference
-
-```bash
-# Full validation
-npm run validate:structure
-
-# Check single file
-npm run validate:structure -- --check "path/to/file.js"
-
-# Check multiple files with glob
-npm run validate:structure -- --files "src/**/*.js"
-
-# Generate manifest
-npm run validate:structure -- --generate-manifest
-
-# Show suggestions for violations
-npm run validate:structure -- --fix
-
-# JSON output for automation
-npm run validate:structure -- --json
-
-# Verbose output
-npm run validate:structure -- --verbose
-```
-
----
-
-## Common Violations & Resolutions
-
-### Scripts at Root Level
-
-**Violation:** `Scripts at root level are not allowed`
-
-**Resolution:**
-- Move to `.aios-core/infrastructure/scripts/{category}/`
-- Example: `scripts/foo.js` → `.aios-core/infrastructure/scripts/foo.js`
-
-### Tools at Root Level
-
-**Violation:** `Tool definitions at root level are not allowed`
-
-**Resolution:**
-- Move to `.aios-core/infrastructure/tools/cli/` for CLI tools
-- Move to `.aios-core/infrastructure/tools/mcp/` for MCP tools
-
-### Agents in Wrong Location
-
-**Violation:** `Agent files at root level are not allowed`
-
-**Resolution:**
-- Move to `.aios-core/development/agents/`
-- Ensure naming follows kebab-case: `{agent-name}.md`
-
-### Tasks in Wrong Location
-
-**Violation:** `Task files at root level are not allowed`
-
-**Resolution:**
-- Move to `.aios-core/development/tasks/`
-- Ensure naming follows kebab-case: `{task-name}.md`
-
----
-
-## Integration Points
-
-- **Pre-commit Hook:** Runs automatically on `git commit`
-- **CI/CD Pipeline:** Can be integrated with `npm run validate:structure -- --json`
-- **Story Workflow:** Executed by @architect before @dev implementation
-
----
-
-## Related Resources
-
-- [Source Tree Structure](../../docs/architecture/source-tree.md)
-- [Coding Standards](../../docs/architecture/coding-standards.md)
-- [Story 6.8: Source-Tree Guardian](../../docs/stories/v2.1/sprint-6/story-6.8-source-tree-guardian.md)
-
----
-
-**Created:** 2025-12-14
-**Author:** @architect (Aria)
-**Story:** 6.8 - Source-Tree Guardian

package/.aios-core/infrastructure/scripts/source-tree-guardian/index.js

@@ -1,375 +0,0 @@
-#!/usr/bin/env node
-/**
- * Source-Tree Guardian - Main Entry Point
- *
- * CLI tool and module exports for source-tree validation.
- *
- * @module source-tree-guardian
- * @version 1.0.0
- * @story 6.8
- */
-
-const path = require('path');
-const fs = require('fs').promises;
-
-// Import core modules
-const {
-  SourceTreeValidator,
-  normalizePath,
-  validateNamingConvention,
-  matchesPattern,
-  loadRules,
-  shouldExclude,
-  validateFilePlacement,
-  getStagedFiles,
-  Severity,
-} = require('./validator');
-
-const {
-  ManifestGenerator,
-  generateTree,
-  countFilesByCategory,
-  getFileStats,
-  FILE_CATEGORIES,
-  DEFAULT_EXCLUSIONS,
-} = require('./manifest-generator');
-
-/**
- * CLI argument parser
- * @param {string[]} args - Command line arguments
- * @returns {Object} Parsed options
- */
-function parseArgs(args) {
-  const options = {
-    help: false,
-    version: false,
-    files: null,
-    stagedOnly: false,
-    generateManifest: false,
-    diff: false,
-    fix: false,
-    json: false,
-    verbose: false,
-    force: false,
-    reason: null,
-    config: null,
-    check: null,
-  };
-
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-
-    switch (arg) {
-      case '-h':
-      case '--help':
-        options.help = true;
-        break;
-      case '-v':
-      case '--version':
-        options.version = true;
-        break;
-      case '--files':
-        options.files = args[++i];
-        break;
-      case '--staged-only':
-        options.stagedOnly = true;
-        break;
-      case '--generate-manifest':
-        options.generateManifest = true;
-        break;
-      case '--diff':
-        options.diff = true;
-        break;
-      case '--fix':
-        options.fix = true;
-        break;
-      case '--json':
-        options.json = true;
-        break;
-      case '--verbose':
-        options.verbose = true;
-        break;
-      case '--force':
-        options.force = true;
-        break;
-      case '--reason':
-        options.reason = args[++i];
-        break;
-      case '--config':
-        options.config = args[++i];
-        break;
-      case '--check':
-        options.check = args[++i];
-        break;
-      default:
-        if (!arg.startsWith('-')) {
-          options.files = arg;
-        }
-    }
-  }
-
-  return options;
-}
-
-/**
- * Prints help message
- */
-function printHelp() {
-  console.log(`
-Source-Tree Guardian - Structure Validation System
-Version: 1.0.0 | Story: 6.8
-
-USAGE:
-  node index.js [options]
-  npm run validate:structure [-- options]
-
-OPTIONS:
-  -h, --help              Show this help message
-  -v, --version           Show version information
-  --files <glob>          Validate specific files (glob pattern)
-  --staged-only           Only validate git staged files
-  --generate-manifest     Generate source-tree-manifest.json
-  --diff                  Show drift from previous manifest
-  --fix                   Show auto-fix suggestions
-  --json                  Output in JSON format
-  --verbose               Enable verbose output
-  --force                 Bypass validation (requires --reason)
-  --reason <text>         Justification for --force (logged)
-  --config <path>         Custom rules file location
-  --check <path>          Check a single file
-
-EXAMPLES:
-  # Validate all files
-  npm run validate:structure
-
-  # Validate specific files
-  npm run validate:structure -- --files "src/**/*.js"
-
-  # Validate staged files only (pre-commit)
-  npm run validate:structure -- --staged-only
-
-  # Generate manifest
-  npm run validate:structure -- --generate-manifest
-
-  # Show drift from previous manifest
-  npm run validate:structure -- --diff
-
-  # JSON output for CI
-  npm run validate:structure -- --json
-
-  # Force bypass with reason
-  npm run validate:structure -- --force --reason "Hotfix deployment"
-`);
-}
-
-/**
- * Prints version information
- */
-function printVersion() {
-  console.log('Source-Tree Guardian v1.0.0');
-  console.log('Story: 6.8 - Source-Tree Guardian - Structure Validation System');
-}
-
-/**
- * Logs force bypass with reason
- * @param {string} reason - Justification for bypass
- * @param {string} projectRoot - Project root directory
- */
-async function logForceBypass(reason, projectRoot) {
-  const logDir = path.join(projectRoot, '.ai');
-  const logFile = path.join(logDir, 'force-bypass-log.md');
-
-  await fs.mkdir(logDir, { recursive: true });
-
-  const entry = `\n## Force Bypass - ${new Date().toISOString()}\n\n**Reason:** ${reason}\n\n---\n`;
-
-  try {
-    await fs.appendFile(logFile, entry);
-    console.log(`⚠️  Force bypass logged to ${logFile}`);
-  } catch (error) {
-    console.warn(`Warning: Could not log force bypass: ${error.message}`);
-  }
-}
-
-/**
- * Main CLI entry point
- * @param {string[]} args - Command line arguments
- * @returns {Promise<number>} Exit code
- */
-async function main(args = process.argv.slice(2)) {
-  const options = parseArgs(args);
-  const projectRoot = process.cwd();
-
-  // Handle help and version
-  if (options.help) {
-    printHelp();
-    return 0;
-  }
-
-  if (options.version) {
-    printVersion();
-    return 0;
-  }
-
-  // Handle force bypass
-  if (options.force) {
-    if (!options.reason) {
-      console.error('❌ --force requires --reason to be specified');
-      return 1;
-    }
-    await logForceBypass(options.reason, projectRoot);
-    console.log('✅ Validation bypassed');
-    return 0;
-  }
-
-  // Handle manifest generation
-  if (options.generateManifest) {
-    const generator = new ManifestGenerator({ projectRoot });
-    console.log('📊 Generating source-tree manifest...');
-
-    const manifest = await generator.generate();
-    const outputPath = await generator.save(manifest);
-
-    if (options.json) {
-      console.log(JSON.stringify(manifest, null, 2));
-    } else {
-      console.log(`✅ Manifest generated: ${outputPath}`);
-      console.log(`   Files: ${manifest.summary.totalFiles}`);
-      console.log(`   Directories: ${manifest.summary.totalDirectories}`);
-      console.log(`   Duration: ${manifest.duration}ms`);
-    }
-    return 0;
-  }
-
-  // Handle diff
-  if (options.diff) {
-    const generator = new ManifestGenerator({ projectRoot });
-    console.log('📊 Comparing with previous manifest...');
-
-    try {
-      const oldManifest = await generator.load();
-      const newManifest = await generator.generate();
-      const diff = generator.compare(oldManifest, newManifest);
-
-      if (options.json) {
-        console.log(JSON.stringify(diff, null, 2));
-      } else {
-        console.log(generator.formatDiffReport(diff));
-      }
-    } catch (error) {
-      if (error.code === 'ENOENT') {
-        console.log('⚠️  No previous manifest found. Generate one first with --generate-manifest');
-        return 1;
-      }
-      throw error;
-    }
-    return 0;
-  }
-
-  // Handle single file check
-  if (options.check) {
-    const validator = new SourceTreeValidator({
-      projectRoot,
-      rulesPath: options.config,
-      verbose: options.verbose,
-    });
-
-    const result = await validator.validateFile(options.check);
-
-    if (options.json) {
-      console.log(JSON.stringify(result, null, 2));
-    } else {
-      if (result.isValid) {
-        console.log(`✅ ${options.check}: Valid placement`);
-      } else {
-        console.log(`❌ ${options.check}: Invalid placement`);
-        for (const v of result.violations) {
-          console.log(`   ${v.message}`);
-          if (v.suggestedLocation) {
-            console.log(`   Suggested: ${v.suggestedLocation}`);
-          }
-        }
-      }
-    }
-
-    return result.isValid ? 0 : 1;
-  }
-
-  // Main validation
-  const validator = new SourceTreeValidator({
-    projectRoot,
-    rulesPath: options.config,
-    verbose: options.verbose,
-  });
-
-  console.log('🔍 Validating source-tree structure...');
-
-  const report = await validator.validate({
-    files: options.files,
-    stagedOnly: options.stagedOnly,
-  });
-
-  // Output report
-  if (options.json) {
-    console.log(validator.formatJsonReport(report));
-  } else {
-    console.log(validator.formatReport(report, { showFixHint: !options.fix }));
-  }
-
-  // Show fix suggestions if requested
-  if (options.fix && report.violations.length > 0) {
-    console.log('\n📋 FIX SUGGESTIONS:\n');
-    const suggestions = validator.generateFixSuggestions(report.violations);
-    for (const suggestion of suggestions) {
-      console.log(`File: ${suggestion.file}`);
-      console.log(`  Current: ${suggestion.currentLocation}`);
-      console.log(`  Suggested: ${suggestion.suggestedLocation}`);
-      if (suggestion.command) {
-        console.log(`  Command: ${suggestion.command}`);
-      }
-      console.log('');
-    }
-  }
-
-  // Return exit code based on errors
-  return report.summary.errors > 0 ? 1 : 0;
-}
-
-// Export modules
-module.exports = {
-  // Validator exports
-  SourceTreeValidator,
-  normalizePath,
-  validateNamingConvention,
-  matchesPattern,
-  loadRules,
-  shouldExclude,
-  validateFilePlacement,
-  getStagedFiles,
-  Severity,
-  // Manifest exports
-  ManifestGenerator,
-  generateTree,
-  countFilesByCategory,
-  getFileStats,
-  FILE_CATEGORIES,
-  DEFAULT_EXCLUSIONS,
-  // CLI exports
-  main,
-  parseArgs,
-};
-
-// Run CLI if executed directly
-if (require.main === module) {
-  main()
-    .then((exitCode) => {
-      process.exit(exitCode);
-    })
-    .catch((error) => {
-      console.error('❌ Error:', error.message);
-      if (process.env.DEBUG) {
-        console.error(error.stack);
-      }
-      process.exit(1);
-    });
-}