🛡️ THZ-SecondHand: Segunda Mão Arquitetural & Automação Assistida

THZ-SecondHand é uma engine/framework genérica e agnóstica de software para governança arquitetural, auditoria normativa (ISO/IEC 42010, 25010, 29148, 27001, ISO 8601), automação de operações de TI (bootstrap, healthchecks, retenção, backups), esteiras de CI/CD, Git Hooks e assistência inteligente baseada em Machine Learning leve.

---

🌟 Recursos Principais

1. 🛡️ Suíte de Auditoria Normativa ISO & RFCs (secondhand audit)

   • ISO/IEC 42010: Valida Descrições de Arquitetura e Registros de Decisão Arquitetural (ADRs).
   • ISO/IEC 25010 (SQuaRE): Audita cobertura de 8 características de qualidade de software (Desempenho, Segurança, Resiliência, etc.).
   • ISO/IEC 29148: Avalia Engenharia de Requisitos, identificando ambiguidade e verificabilidade de especificações.
   • ISO/IEC 27001: Audita controles de segurança, vazamento de segredos/chaves hardcoded e criptografia.
   • ISO 8601: Valida padronização de datas e horários em formato ISO (YYYY-MM-DD).
   • Fronteiras Arquiteturais: Impede importações cruzadas proibidas em Monólitos Modulares e Bounded Contexts.

2. 🧠 Assistente de Machine Learning Leve (secondhand ml)

   • Architectural Drift Detector: Identifica anomalias estruturais na base de código usando IsolationForest (ou fallback estatístico Z-score).
   • Requirement Ambiguity Classifier: Classifica frases de especificações com TF-IDF + Naive Bayes (ou NLP heurístico) para apontar ambiguidades (ISO 29148 ML).
   • Commit Risk Assessor: Avalia a volatilidade e o risco de alterações em arquivos sensíveis antes do merge.

3. 🤖 Guardrails para Agentes de IA (secondhand agent)

   • Sincroniza e gera arquivos de diretrizes (.agent/AGENTS.md, SYSTEM_PROMPT.md, PLAN.md, .cursorrules) adaptados a qualquer stack para orientar assistentes de código AI (Antigravity, Cursor, Copilot, Claude).

4. ⚡ Automação de Operações & Retenção (secondhand ops)

   • Bootstrap Autônomo: Verifica pré-requisitos, gera .env e inicializa containers Docker.
   • Healthcheck Universal: Avalia a saúde de endpoints HTTP, conexões PostgreSQL e Redis.
   • Housekeeping Engine: Rotação automatizada e política de retenção de backups, logs e relatórios HTML.
   • Backup Engine: Snapshots comprimidos com carimbo de data/hora.

5. ⚙️ Pipelines de CI/CD & Git Hooks (secondhand pipeline)

   • Instalação de Git Hooks (pre-commit, commit-msg) exigindo mensagens em Conventional Commits e zero segredos expostos.
   • Gerador de workflows automatizados para GitHub Actions e GitLab CI.

---

🚀 Instalação e Uso Rápido

1. Inicializar no seu Projeto Target

# Navegue até a raiz do seu projeto e execute
/caminho/para/THZ-SecondHand/bin/secondhand init --dir .

Isso criará o arquivo de configuração secondhand.config.json e a pasta .agent/ com todas as diretrizes para IA.

2. Executar Auditoria Arquitetural

/caminho/para/THZ-SecondHand/bin/secondhand audit --dir .

Os relatórios interativos em HTML serão salvos em docs/relatorios-html/latest/relatorio_conformidade.html.

3. Assistência de ML & Avaliação de Ambiguidade

# Avaliar desvio de arquitetura
/caminho/para/THZ-SecondHand/bin/secondhand ml drift

# Avaliar ambiguidade em especificação (ISO 29148 ML)
/caminho/para/THZ-SecondHand/bin/secondhand ml ambiguity --text "O sistema deve ser rápido e amigável tbd."

# Avaliar risco de alteração em commit
/caminho/para/THZ-SecondHand/bin/secondhand ml risk --files apps/api/src/modules/auth/auth.service.ts

4. Operações & Housekeeping

# Executar Healthcheck de serviços
/caminho/para/THZ-SecondHand/bin/secondhand ops healthcheck

# Limpeza e Rotação de relatórios e backups antigos
/caminho/para/THZ-SecondHand/bin/secondhand ops housekeep

# Backup snapshot da base de código
/caminho/para/THZ-SecondHand/bin/secondhand ops backup

5. Instalar Git Hooks Automatizados

/caminho/para/THZ-SecondHand/bin/secondhand pipeline hooks

---

🏛️ Estrutura Interna do THZ-SecondHand

THZ-SecondHand/
├── bin/
│   └── secondhand                  # Executável CLI principal
├── secondhand.config.json.template # Template de configuração
├── requirements.txt                # Dependências Python (opcionais/mínimas)
├── src/
│   ├── core/                       # Configuração, detector de stack e regras abstratas
│   ├── linters/                    # Linters ISO 42010, 25010, 29148, 27001, 8601 & HTML Reporter
│   ├── ml/                         # Drift detector, classificador de ambiguidade & avaliador de risco
│   ├── agent/                      # Gerador de guardrails e regras para Agentes de IA
│   ├── ops/                        # Bootstrap, healthcheck, housekeeping & backups
│   ├── pipelines/                  # Instalador de Git Hooks e workflows de CI/CD
│   └── governance/                 # Templates de ADRs, Especificações e Guias de Engenharia
└── README.md

---

📜 Normas & Padrões Atendidos

• ISO/IEC 42010:2011: Architecture Description
• ISO/IEC 25010:2011: SQuaRE Software Quality Requirements
• ISO/IEC 29148:2018: Requirements Engineering
• ISO/IEC 27001:2022: Information Security Management
• ISO 8601: Representation of Dates and Times
• RFC 4122 / RFC 9562: Universally Unique Identifiers (UUIDv4/v7)
• RFC 7519: JSON Web Token (JWT)

---

📄 Licença

Licenciado sob a Licença MIT - Reutilizável em qualquer software livre ou proprietário.