Especificação de Auto-Recuperação do HCS

Problema Detectado
     │
     ▼
┌─────────────────┐
│ A correção é    │
│ trivial e       │
│ reversível?     │
└────────┬────────┘
         │
    Sim  │  Não
    ▼    │  ▼
┌────────┴──────────┐
│                   │
▼                   ▼
Nível 1          ┌─────────────────┐
Auto-corrigir    │ A correção      │
silenciosamente  │ modifica dados/ │
                 │ código do       │
                 │ usuário?        │
                 └────────┬────────┘
                          │
                     Não  │   Sim
                     ▼    │   ▼
                 ┌────────┴──────────┐
                 │                   │
                 ▼                   ▼
              Nível 2            Nível 3
              Solicitar          Guia
              Usuário            Manual

# Problemas de Nível 1 - auto-corrigir silenciosamente
- id: PC-001
  description: '.aios/config.yaml ausente'
  severity: CRITICAL
  tier: 1
  action: recreate_config
  message: 'Config recriado a partir do template'
 
- id: LE-005
  description: 'Servidor MCP não respondendo'
  severity: HIGH
  tier: 1
  action: restart_mcp
  message: 'Servidor MCP reiniciado'
 
- id: RH-008
  description: '.gitignore incompleto'
  severity: LOW
  tier: 1
  action: append_gitignore
  message: 'Entradas ausentes adicionadas ao .gitignore'

✅ 3 problemas auto-corrigidos:
   • Recriado .aios/config.yaml (backup: .aios/backups/config.yaml.1735564800)
   • Reiniciado servidor MCP context7
   • Adicionado .aios/cache/ ao .gitignore

# Problemas de Nível 2 - solicitar usuário
- id: PC-003
  description: 'coding-standards.md ausente'
  severity: MEDIUM
  tier: 2
  action: create_missing_docs
  prompt: 'Criar coding-standards.md a partir do template?'
  options:
    - 'yes' # Criar arquivo
    - 'no' # Pular
    - 'custom' # Deixar usuário especificar local
 
- id: RH-006
  description: '3 pacotes desatualizados (patches de segurança)'
  severity: MEDIUM
  tier: 2
  action: update_deps
  prompt: 'Atualizar 3 pacotes com patches de segurança?'
  details:
    - 'lodash: 4.17.20 → 4.17.21 (segurança)'
    - 'axios: 0.21.0 → 0.21.4 (segurança)'
    - 'yaml: 2.0.0 → 2.3.4 (segurança)'

⚠️ Encontrados 2 problemas que requerem confirmação:

[1/2] coding-standards.md ausente
      Ação: Criar a partir do template
      Local: docs/framework/coding-standards.md

      Aplicar correção? [S]im / [N]ão / [P]ular todos: s

      ✅ Criado docs/framework/coding-standards.md

[2/2] 3 pacotes têm atualizações de segurança
      Ação: npm update lodash axios yaml
      Backup: package-lock.json.backup

      Aplicar correção? [S]im / [N]ão / [P]ular todos: s

      ✅ 3 pacotes atualizados

# Problemas de Nível 3 - apenas guia manual
- id: PC-002
  description: "Tarefa referencia agente inexistente 'legacy-dev'"
  severity: HIGH
  tier: 3
  guide:
    title: 'Corrigir Referência de Agente Inválida'
    steps:
      - 'Abrir .aios-core/development/tasks/deploy.md'
      - 'Encontrar linha: agent: legacy-dev'
      - 'Substituir por: agent: devops'
      - 'Verificar com: npx aios task validate deploy'
    suggested_agent: '@architect'
 
- id: RH-007
  description: 'Vulnerabilidade crítica em dependência de produção'
  severity: CRITICAL
  tier: 3
  guide:
    title: 'Vulnerabilidade de Segurança Crítica'
    details: 'CVE-2024-XXXXX em express@4.17.0'
    steps:
      - 'Revisar detalhes do CVE: https://nvd.nist.gov/vuln/detail/CVE-2024-XXXXX'
      - 'Verificar se a vulnerabilidade afeta seu uso'
      - 'Se afetado, executar: npm audit fix --force'
      - 'Testar aplicação completamente após atualização'
      - 'Considerar consultar @architect para mudanças que quebram compatibilidade'
    urgency: 'IMEDIATO'
    external_link: 'https://nvd.nist.gov/vuln/detail/CVE-2024-XXXXX'
 
- id: DE-004
  description: 'Certificado SSL expira em 7 dias'
  severity: CRITICAL
  tier: 3
  guide:
    title: 'Aviso de Expiração de Certificado SSL'
    steps:
      - 'Contate seu provedor de SSL ou equipe de TI'
      - 'Renove o certificado antes da expiração'
      - 'Atualize o certificado no ambiente de implantação'
    suggested_agent: '@devops'

❌ Encontrados 2 problemas que requerem intervenção manual:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
[CRÍTICO] Aviso de Expiração de Certificado SSL
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Seu certificado SSL expira em 7 dias.

Passos para resolver:
  1. Contate seu provedor de SSL ou equipe de TI
  2. Renove o certificado antes da expiração
  3. Atualize o certificado no ambiente de implantação

Sugerido: Ativar @devops para assistência
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

[ALTO] Corrigir Referência de Agente Inválida
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Tarefa 'deploy' referencia agente inexistente 'legacy-dev'.

Passos para resolver:
  1. Abrir .aios-core/development/tasks/deploy.md
  2. Encontrar linha: agent: legacy-dev
  3. Substituir por: agent: devops
  4. Verificar com: npx aios task validate deploy

Sugerido: Ativar @architect para revisão
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

neverAutoFix:
  files:
    - '**/*.{js,ts,jsx,tsx,py,go,rs}' # Código fonte
    - '**/*.{json,yaml,yml}' # Config do usuário (fora de .aios/)
    - '.env*' # Arquivos de ambiente
    - '**/secrets/**' # Segredos
    - '**/credentials*' # Credenciais
    - '.git/**' # Internos do Git
    - 'package.json' # Dependências do usuário
    - 'tsconfig.json' # Config do usuário
    - '.eslintrc*' # Regras de linting do usuário
 
  operations:
    - delete_user_files # Nunca deletar arquivos do usuário
    - modify_git_history # Nunca reescrever histórico do git
    - change_remote_urls # Nunca modificar remotes
    - push_to_remote # Nunca fazer push automático
    - modify_ci_secrets # Nunca tocar em segredos de CI
    - change_permissions_recursive # Nunca chmod -R
 
  conditions:
    - file_has_uncommitted_changes # Não tocar em arquivos modificados
    - file_size_exceeds_1mb # Arquivos grandes precisam de revisão
    - path_outside_project # Permanecer nos limites do projeto

safeToAutoFix:
  paths:
    - '.aios/**' # Arquivos de workspace do AIOS
    - '.aios-core/**/*.yaml' # YAML do framework (cuidado)
    - '.claude/**' # Configuração do Claude
    - '.vscode/settings.json' # Apenas configurações da IDE
    - '.cursor/**' # Config da IDE Cursor
    - 'node_modules/.cache/**' # Arquivos de cache
 
  conditions:
    - file_is_regenerable # Pode ser recriado a partir do template
    - file_has_backup # Backup existe
    - action_is_reversible # Pode ser desfeito
    - user_initiated_check # Usuário executou health-check

async function validateFix(check, action) {
  // 1. Verificar se ação está na lista de permissão
  if (!SAFE_ACTIONS.includes(action.type)) {
    return { allowed: false, reason: 'Ação não está na lista segura' };
  }
 
  // 2. Verificar se caminho do arquivo é seguro
  if (!isPathSafe(action.targetPath)) {
    return { allowed: false, reason: 'Caminho não está em zona segura' };
  }
 
  // 3. Verificar se arquivo não foi modificado
  if (await hasUncommittedChanges(action.targetPath)) {
    return { allowed: false, reason: 'Arquivo tem alterações não commitadas' };
  }
 
  // 4. Garantir que backup pode ser criado
  if (action.requiresBackup && !(await canCreateBackup(action.targetPath))) {
    return { allowed: false, reason: 'Não é possível criar backup' };
  }
 
  // 5. Verificar se ação é reversível
  if (!action.rollbackCommand) {
    return { allowed: false, reason: 'Nenhum procedimento de rollback definido' };
  }
 
  return { allowed: true };
}

.aios/
├── backups/
│   ├── health-check-2025-12-30T10-30-00/
│   │   ├── manifest.json           # O que foi backed up
│   │   ├── config.yaml             # Arquivos backed up
│   │   ├── settings.json
│   │   └── package-lock.json
│   ├── health-check-2025-12-29T14-20-00/
│   │   └── ...
│   └── .retention                  # Política de retenção

{
  "id": "health-check-2025-12-30T10-30-00",
  "created": "2025-12-30T10:30:00.000Z",
  "checkId": "HC-20251230-103000",
  "issuesFixed": 3,
  "files": [
    {
      "original": ".aios/config.yaml",
      "backup": "config.yaml",
      "action": "recreate_config",
      "checksum": "sha256:abc123...",
      "size": 2048
    }
  ],
  "rollbackCommand": "npx aios health-check --rollback health-check-2025-12-30T10-30-00"
}

# .aios/backups/.retention
retention:
  maxBackups: 10 # Manter últimos 10 backups
  maxAge: 7 # dias
  minKeep: 3 # Sempre manter pelo menos 3
  autoCleanup: true # Limpar backups antigos automaticamente

async function createBackup(action) {
  const backupId = `health-check-${new Date().toISOString().replace(/[:.]/g, '-')}`;
  const backupDir = path.join('.aios', 'backups', backupId);
 
  await fs.ensureDir(backupDir);
 
  const manifest = {
    id: backupId,
    created: new Date().toISOString(),
    files: [],
  };
 
  for (const file of action.filesToBackup) {
    const content = await fs.readFile(file);
    const checksum = crypto.createHash('sha256').update(content).digest('hex');
    const backupName = path.basename(file);
 
    await fs.writeFile(path.join(backupDir, backupName), content);
 
    manifest.files.push({
      original: file,
      backup: backupName,
      checksum: `sha256:${checksum}`,
      size: content.length,
    });
  }
 
  await fs.writeJson(path.join(backupDir, 'manifest.json'), manifest, { spaces: 2 });
 
  return { backupId, backupDir, manifest };
}

async function applyFixWithRollback(check, action) {
  const backup = await createBackup(action);
 
  try {
    await action.execute();
    await verifyFix(check);
 
    return { success: true, backup: backup.backupId };
  } catch (error) {
    console.error(`Correção falhou: ${error.message}`);
    console.log(`Fazendo rollback do backup: ${backup.backupId}`);
 
    await rollback(backup);
 
    return { success: false, error: error.message, rolledBack: true };
  }
}

# Rollback de backup específico
npx aios health-check --rollback health-check-2025-12-30T10-30-00
 
# Listar backups disponíveis
npx aios health-check --list-backups
 
# Rollback do último backup
npx aios health-check --rollback-last

async function rollback(backupId) {
  const backupDir = path.join('.aios', 'backups', backupId);
  const manifest = await fs.readJson(path.join(backupDir, 'manifest.json'));
 
  console.log(`Fazendo rollback de ${manifest.files.length} arquivos...`);
 
  for (const file of manifest.files) {
    const backupPath = path.join(backupDir, file.backup);
    const content = await fs.readFile(backupPath);
 
    // Verificar checksum
    const checksum = crypto.createHash('sha256').update(content).digest('hex');
    if (`sha256:${checksum}` !== file.checksum) {
      throw new Error(`Backup corrompido: ${file.original}`);
    }
 
    await fs.writeFile(file.original, content);
    console.log(`  ✅ Restaurado: ${file.original}`);
  }
 
  console.log('Rollback completo.');
}

.aios-core/core/health-check/
├── healers/
│   ├── index.js              # Registro de healers
│   ├── tier1/
│   │   ├── recreate-config.js
│   │   ├── clear-cache.js
│   │   ├── restart-mcp.js
│   │   └── fix-permissions.js
│   ├── tier2/
│   │   ├── update-deps.js
│   │   ├── fix-ide-config.js
│   │   └── create-docs.js
│   └── tier3/
│       ├── manual-guide-generator.js
│       └── escalation-handler.js
├── backup/
│   ├── backup-manager.js
│   ├── retention-policy.js
│   └── rollback-handler.js
└── safety/
    ├── allowlist.js
    ├── blocklist.js
    └── validator.js

// Interface base do healer
class BaseHealer {
  constructor(options = {}) {
    this.tier = options.tier || 1;
    this.requiresBackup = options.requiresBackup || true;
    this.requiresConfirmation = options.requiresConfirmation || false;
  }
 
  // Sobrescrever na subclasse
  async canHeal(issue) {
    throw new Error('Não implementado');
  }
 
  // Sobrescrever na subclasse
  async heal(issue, context) {
    throw new Error('Não implementado');
  }
 
  // Sobrescrever na subclasse
  async verify(issue) {
    throw new Error('Não implementado');
  }
 
  // Rollback comum
  async rollback(backupId) {
    return await rollbackManager.rollback(backupId);
  }
}
 
// Exemplo de healer Nível 1
class RecreateConfigHealer extends BaseHealer {
  constructor() {
    super({ tier: 1, requiresBackup: true, requiresConfirmation: false });
  }
 
  async canHeal(issue) {
    return issue.id === 'PC-001' && !(await fs.pathExists('.aios/config.yaml'));
  }
 
  async heal(issue, context) {
    const template = await fs.readFile('.aios-core/templates/config-template.yaml');
    await fs.writeFile('.aios/config.yaml', template);
    return { success: true, message: 'Config recriado a partir do template' };
  }
 
  async verify(issue) {
    return await fs.pathExists('.aios/config.yaml');
  }
}

// .aios/logs/self-healing.log
const healingLog = {
  append: async (entry) => {
    const logPath = '.aios/logs/self-healing.log';
    const logEntry = {
      timestamp: new Date().toISOString(),
      ...entry,
    };
    await fs.appendFile(logPath, JSON.stringify(logEntry) + '\n');
  },
};
 
// Uso
await healingLog.append({
  action: 'recreate_config',
  tier: 1,
  issue: 'PC-001',
  backup: 'health-check-2025-12-30T10-30-00',
  result: 'success',
  duration: '45ms',
});