stealthos-cli 0.1.0-alpha.3 → 0.1.0-alpha.5

package/ai/governance/engineering-principles.md

@@ -0,0 +1,70 @@
+---
+version: 1.0.0
+updated: 2026-05-15
+tier: conditional
+tokens: ~700
+load: architecture, design, refactor, review
+triggers: princípio, principle, fundamentos, governança
+---
+
+# Engineering Principles
+
+> Princípios que governam toda decisão técnica neste OS. Quando houver dúvida, voltar aqui.
+
+---
+
+## P1 — Simplicidade vence sofisticação
+
+Se há duas soluções, escolha a mais simples que funciona. Sofisticação só é justificada quando há requisito claro (escala, segurança, regulação). Anti-padrão: prematuramente introduzir microsserviços, ORM customizado, framework próprio.
+
+## P2 — Causa raiz, não sintoma
+
+Bug nunca é fechado com workaround silencioso. Identifique a causa, corrija, documente em `memory/errors-and-solutions.md`. Se urgência exige workaround, registre como `known-issue` com data de validade.
+
+## P3 — Menor mudança que resolve
+
+Refator oportunista é proibido em PR de feature/bug. Cada mudança tem 1 objetivo declarado.
+
+## P4 — Reversibilidade
+
+Toda decisão deve responder: "como desfazer se errado?". Migrações têm script de rollback; deploys têm canário/blue-green; ADRs têm seção "consequências negativas".
+
+## P5 — Spec antes de código
+
+Não escrever código sem PRD + SDD (para features) ou RFC (para mudanças cross-cutting). Bug-fix pequeno é exceção, mas deve atualizar o doc associado se a regra mudou.
+
+## P6 — Memória explícita
+
+Decisão tomada, registrar. Erro encontrado, registrar. Padrão emergente, registrar. O cérebro está no disco, não no chat.
+
+## P7 — Custo é restrição
+
+Toda escolha que adiciona custo (financeiro, complexidade, manutenção) é justificada em ADR. Default é não adicionar.
+
+## P8 — Defesa em camadas
+
+Validação no front + no back + no DB. Segurança no perímetro + na camada de aplicação + nos dados. Resiliência via timeouts + retries + circuit breakers + fallbacks.
+
+## P9 — Observabilidade desde o dia 1
+
+Sem logs estruturados + metrics + traces, qualquer sistema cresce no escuro. Logs com prefixo `[MODULE]`, métricas com nome em `snake_case`, traces propagados via `x-trace-id`.
+
+## P10 — Não inventar
+
+`rules/dont.md` regra 1. Se não tem certeza, leia o código, rode comando, ou pergunte. APIs/flags/versões nunca são chutadas.
+
+---
+
+## Princípios derivados (operacionais)
+
+- **YAGNI** (You Aren't Gonna Need It) — derivado de P1.
+- **Boy Scout** — derivado de P3 invertido: deixe **igual ou melhor**, mas dentro do escopo da PR.
+- **Trunk-based** — branches curtas; ramos longos viram conflito e divergência.
+- **Test first, when it pays** — TDD para regras críticas; smoke depois para UI.
+- **Documentation as code** — markdown versionado >> wiki externo.
+
+---
+
+## Quando questionar um princípio
+
+Quando 3+ casos reais mostrarem que o princípio prejudica mais que ajuda. Abrir entrada em `evolution/improvements.md`, validar, escalar para ADR de mudança.

package/ai/governance/quality-gates.md

@@ -0,0 +1,85 @@
+---
+version: 1.0.0
+updated: 2026-05-15
+tier: conditional
+tokens: ~600
+load: pipeline, gate, review, deploy
+triggers: gate, qualidade, quality, checkpoint
+---
+
+# Quality Gates
+
+> Pontos obrigatórios de validação no pipeline. O fluxo IDEIA → DEPLOY só avança quando o gate atual passa. Cada gate tem **owner** (humano OU agente) e **artefato de saída**.
+
+---
+
+## Pipeline canônico (referência: `core/pipeline/execution-engine.md`)
+
+```
+G1   G2   G3    G4   G5    G6    G7    G8     G9      G10
+IDEIA→PRD→ARCH→SDD→TASKS→IMPL→TEST→REVIEW→DEPLOY→OBSERVE→LEARN
+```
+
+| Gate | Nome | Owner | Artefato | Critério |
+|---|---|---|---|---|
+| **G1** | Discovery aprovado | `product-manager` agent + Founder | PRD draft | Problema, objetivo, KPIs, personas, escopo claros |
+| **G2** | PRD aprovado | Founder | PRD final | Requisitos funcionais + não-funcionais + critérios de aceite |
+| **G3** | Arquitetura aprovada | `architect` agent + Founder | SDD + ADRs | Decisões justificadas, alternativas listadas, riscos |
+| **G4** | Tasks definidas | `tech-lead` agent | Backlog | Cada task atende DoR (`governance/definition-of-ready.md`) |
+| **G5** | Implementação | `backend/frontend-engineer` | Código + testes unit | Build verde, types OK, testes unit passam |
+| **G6** | QA aprovado | `qa-engineer` agent | Testes E2E + edge cases | Cobertura subiu ou manteve, edge cases cobertos |
+| **G7** | Review aprovado | `reviewer` agent + humano | PR aprovada | Diff revisado, conformidade com `governance/*` |
+| **G8** | Deploy autorizado | `sre-engineer` agent | Plano de deploy + rollback | Pré-deploy checklist OK, janela respeitada |
+| **G9** | Observabilidade ativa | `sre-engineer` agent | Dashboards + alertas | Métrica de sucesso instrumentada, alertas no canal |
+| **G10** | Aprendizado registrado | qualquer agent | Entrada em `evolution/` | Lessons learned, patterns ou anti-patterns |
+
+---
+
+## Como o agente sinaliza um gate
+
+```
+[GATE G3 — Arquitetura]
+Status: ✅ aprovado | ⏸ aguardando aprovação humana | ❌ bloqueado
+
+Artefato: .ai/specs/SDD/SDD-007-events-heatmap.md
+Decisão pendente: ADR-0042 — Cassandra vs PostgreSQL para hot path
+
+Próximo gate: G4 — Task Breakdown (owner: tech-lead)
+```
+
+## Gates parciais (não-todos os projetos precisam de todos)
+
+| Cenário | Gates obrigatórios | Gates opcionais |
+|---|---|---|
+| Bug fix P0 | G5, G6, G7, G8, G9 | G1-G4 (skip) |
+| Feature nova | G1-G10 (todos) | — |
+| Refator interno | G3 (mini), G5, G6, G7 | G1, G2, G4, G8, G9 |
+| Spike / pesquisa | G1, G10 | resto skip |
+| Mudança de config | G7, G8, G9 | resto skip |
+
+Skip de gate deve aparecer no Audit: `Gates skipped: G2, G4 (motivo: bug fix P0, escopo cirúrgico)`.
+
+---
+
+## Falha de gate
+
+Quando um gate falha, o agente:
+1. Para o pipeline.
+2. Registra em `memory/known-issues.md` se for problema sistêmico.
+3. Devolve para o gate anterior com diagnóstico:
+   ```
+   [GATE G5] FALHOU
+   Causa: build vermelho em tsc server (1 erro em foo.ts:42)
+   Ação: voltar para G5 com fix; manter PR open.
+   ```
+
+Repetir falha do mesmo gate em 3+ tasks → revisar o gate (talvez está mal calibrado) em `improvements.md`.
+
+---
+
+## Anti-padrões
+
+- Pular G3 (arquitetura) em feature complex → deriva inevitável.
+- Pular G6 (QA) em bug crítico → bug volta.
+- "Aprovar" gate sem artefato escrito — só vale com doc no `.ai/`.
+- Founder fazer manual override em todos os gates → use override moderado, registre em `decisions.md`.

package/ai/governance/security-policies.md

@@ -0,0 +1,84 @@
+---
+version: 1.0.0
+updated: 2026-05-15
+tier: conditional
+tokens: ~500
+load: security, auth, secret, vulnerability
+triggers: segurança, security, auth, autenticação, senha, password, token, vuln, lgpd, gdpr
+---
+
+# Security Policies
+
+> Políticas mínimas que se aplicam a todos os projetos sob este OS. Específicas por projeto vivem em `operating-system/security-rules.md`.
+
+---
+
+## P-SEC-1 — Segredos fora do código
+
+- **Nunca** commitar `.env`, chaves, tokens, dumps de credencial.
+- `.env` SEMPRE no `.gitignore` e adicionado em template `*.example`.
+- Secret manager (1Password, Vault, AWS SSM, Doppler) para produção.
+- Rotação obrigatória após exposição acidental + log do incidente em `memory/errors-and-solutions.md`.
+
+## P-SEC-2 — Autenticação e autorização
+
+- Senhas hash com `bcrypt`/`argon2` (custo ≥10).
+- JWT com expiração curta (≤1h) + refresh token rotativo.
+- Default-deny: rota pública é a exceção, declarada.
+- Princípio do menor privilégio em DB users, cloud roles, MCPs.
+
+## P-SEC-3 — Validação de input
+
+- **Validar no perímetro** (request body, query string, headers).
+- Usar lib de schema (`zod`, `joi`, `valibot`) — não validar manualmente.
+- Rejeitar antes de tocar lógica de negócio.
+- Sanitizar antes de renderizar (XSS) e antes de SQL (SQL injection).
+
+## P-SEC-4 — Logging seguro
+
+- **Nunca** logar valores de variáveis sensíveis (senha, token, cartão, CPF parcial).
+- Logs estruturados com filtro de PII no transporte.
+- `[MODULE]` prefix obrigatório (ver `governance/engineering-principles.md` P9).
+
+## P-SEC-5 — Dependências
+
+- Lockfile commitado (`package-lock.json`, `pnpm-lock.yaml`, etc.).
+- Audit semanal: `npm audit --production`, `pip-audit`, `cargo audit`.
+- Dep major (semver-breaking) upgrade exige ADR.
+
+## P-SEC-6 — Threat modeling
+
+Para qualquer feature que toca dados sensíveis, criar entrada em `architecture/threat-modeling.md`:
+- O que está sendo protegido?
+- De quem (atores)?
+- Como (vetores)?
+- Mitigações?
+
+Usar STRIDE mínimo (Spoofing, Tampering, Repudiation, Info Disclosure, DoS, Elevation of Privilege).
+
+## P-SEC-7 — Compliance (quando aplicável)
+
+- **LGPD/GDPR**: registrar bases legais, ter `/privacy` endpoint, suportar export/delete.
+- **PCI-DSS**: nunca armazenar PAN não-criptografado; usar tokenização do provedor.
+- **HIPAA**: BAA + criptografia at-rest e in-transit + auditoria de acesso.
+
+Cada um desses requisitos vira ADR no projeto + entrada em `operating-system/security-rules.md`.
+
+---
+
+## Em PR de feature/bug
+
+Reviewer (humano ou `security-engineer` agent) DEVE confirmar:
+- [ ] Sem segredo no diff
+- [ ] Inputs validados
+- [ ] Outputs não vazam PII em logs
+- [ ] Sem `eval`, `Function()`, `child_process.exec(unescaped)`
+- [ ] Sem `dangerouslySetInnerHTML` sem sanitize
+- [ ] Sem `cors({ origin: '*' })` em prod
+
+## Em incidente
+
+1. **Conter** — desabilitar feature flag, revogar token, isolar host.
+2. **Comunicar** — registrar timestamp + impact em `memory/known-issues.md`.
+3. **Investigar** — causa-raiz, em `memory/errors-and-solutions.md`.
+4. **Aprender** — entrada em `evolution/learnings.md` se padrão emergir.

package/ai/hooks/enforce-audit.ps1

@@ -0,0 +1,41 @@
+# Stop hook
+# Roda quando o agente termina seu turno.
+# Verifica se transcript do turno contem [OS Audit] para tarefas nao-triviais.
+
+$projectDir = $env:CLAUDE_PROJECT_DIR
+if (-not $projectDir) { $projectDir = (Get-Location).Path }
+
+$raw = [Console]::In.ReadToEnd()
+try {
+    $payload = $raw | ConvertFrom-Json
+} catch {
+    exit 0
+}
+
+$transcriptPath = $payload.transcript_path
+if (-not $transcriptPath -or -not (Test-Path $transcriptPath)) {
+    exit 0
+}
+
+# Le ultimas linhas da transcript
+$lines = Get-Content $transcriptPath -Tail 100 -ErrorAction SilentlyContinue
+if (-not $lines) { exit 0 }
+
+$transcriptText = $lines -join "`n"
+
+# Heuristica: se houve tool calls de Edit/Write neste turno e nao ha [OS Audit] na resposta final
+$hasEdits = $transcriptText -match '"tool_name"\s*:\s*"(Edit|Write|NotebookEdit)"'
+$hasAudit = $transcriptText -match '\[OS Audit\]'
+$hasTrivialMark = $transcriptText -match '\[OS Audit\] skipped: trivial'
+
+if ($hasEdits -and -not $hasAudit -and -not $hasTrivialMark) {
+    # Pede ao agente para completar o audit antes de parar
+    $response = @{
+        decision = "block"
+        reason = "Protocolo nao cumprido: tarefa fez edicoes mas nao emitiu [OS Audit]. Adicione o bloco de audit no formato definido em .ai/CONTRACT.md antes de encerrar:`n[OS Audit]`n- Files touched: ...`n- Memory updated: ...`n- Validations: ...`n- Decisions: ...`n- Open items: ..."
+    } | ConvertTo-Json -Depth 5 -Compress
+    Write-Output $response
+    exit 0
+}
+
+exit 0

package/ai/hooks/enforce-audit.sh

@@ -0,0 +1,39 @@
+#!/usr/bin/env bash
+# Stop hook (Unix)
+# Verifica se transcript contem [OS Audit] para tarefas com edicoes.
+set -euo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+PAYLOAD=$(cat)
+
+TRANSCRIPT_PATH=""
+if command -v python3 &>/dev/null; then
+    TRANSCRIPT_PATH=$(echo "$PAYLOAD" | python3 -c 'import sys,json
+try:
+    d=json.load(sys.stdin); print(d.get("transcript_path",""))
+except: pass' 2>/dev/null || echo "")
+elif command -v node &>/dev/null; then
+    TRANSCRIPT_PATH=$(echo "$PAYLOAD" | node -e 'let s="";process.stdin.on("data",d=>s+=d).on("end",()=>{try{console.log(JSON.parse(s).transcript_path||"")}catch{}})' 2>/dev/null || echo "")
+fi
+
+[[ -z "$TRANSCRIPT_PATH" || ! -f "$TRANSCRIPT_PATH" ]] && exit 0
+
+# Pega as ultimas 100 linhas
+TAIL_TEXT=$(tail -n 100 "$TRANSCRIPT_PATH" 2>/dev/null || echo "")
+[[ -z "$TAIL_TEXT" ]] && exit 0
+
+HAS_EDITS=0
+HAS_AUDIT=0
+HAS_TRIVIAL=0
+
+echo "$TAIL_TEXT" | grep -Eq '"tool_name"[[:space:]]*:[[:space:]]*"(Edit|Write|NotebookEdit)"' && HAS_EDITS=1
+echo "$TAIL_TEXT" | grep -Fq '[OS Audit]' && HAS_AUDIT=1
+echo "$TAIL_TEXT" | grep -Fq '[OS Audit] skipped: trivial' && HAS_TRIVIAL=1
+
+if [[ $HAS_EDITS -eq 1 && $HAS_AUDIT -eq 0 && $HAS_TRIVIAL -eq 0 ]]; then
+    REASON='Protocolo nao cumprido: tarefa fez edicoes mas nao emitiu [OS Audit]. Adicione o bloco de audit conforme .ai/CONTRACT.md antes de encerrar:\n[OS Audit]\n- Files touched: ...\n- Memory updated: ...\n- Validations: ...\n- Decisions: ...\n- Open items: ...'
+    printf '{"decision":"block","reason":"%s"}\n' "$REASON"
+    exit 0
+fi
+
+exit 0

package/ai/hooks/guard-edit.ps1

@@ -0,0 +1,182 @@
+# PreToolUse hook (Windows / PowerShell) — matcher: Edit|Write|NotebookEdit|Bash
+# Bloqueia mudancas em arquivos protegidos do AI OS sem confirmacao explicita.
+# Para Bash, faz split em SUBCOMANDOS por separadores (&&, ||, ;, |, newline) e
+# bloqueia apenas o subcomando que contem write verb + path protegido juntos.
+# Override autorizado: criar .claude\.unlock (mera existencia = bypass total).
+
+$projectDir = $env:CLAUDE_PROJECT_DIR
+if (-not $projectDir) { $projectDir = (Get-Location).Path }
+
+# Bypass via sentinela
+$unlockPath = Join-Path $projectDir '.claude\.unlock'
+if (Test-Path $unlockPath) { exit 0 }
+
+# Ler payload do hook
+$raw = [Console]::In.ReadToEnd()
+try {
+    $payload = $raw | ConvertFrom-Json
+} catch {
+    exit 0
+}
+
+$toolName = $payload.tool_name
+
+# Paths PROTEGIDOS (substring match, normalizado para / lower-case)
+$protectedSubstrings = @(
+    '.ai/rules/dont.md',
+    '.ai/contract.md',
+    '.ai/router.md',
+    '.ai/manifest.json',
+    '.ai/hooks/inject-os-reminder.ps1',
+    '.ai/hooks/inject-os-reminder.sh',
+    '.ai/hooks/guard-edit.ps1',
+    '.ai/hooks/guard-edit.sh',
+    '.ai/hooks/enforce-audit.ps1',
+    '.ai/hooks/enforce-audit.sh',
+    '.claude/settings.json'
+)
+
+# Verbos de escrita (regex); se houver match no subcomando + path protegido no mesmo, bloqueia.
+$writeVerbPatterns = @(
+    'Set-Content', 'Out-File', 'Add-Content', 'Clear-Content',
+    'Tee-Object', 'New-Item', 'Remove-Item', 'Move-Item', 'Copy-Item',
+    'fs\.writeFile', 'fs\.appendFile', 'fs\.unlink', 'fs\.rm',
+    'fs\.rmdir', '\brm\s', '\bmv\s', '\bcp\s', '\btee\s',
+    'sed\s+-i', '\bawk\b.*>', '>\s*[^\s|&]', '>>\s*[^\s|&]'
+)
+
+function Test-ProtectedPath([string]$path) {
+    if (-not $path) { return $false }
+    $norm = ($path -replace '\\', '/').ToLower()
+    foreach ($p in $protectedSubstrings) {
+        if ($norm.Contains($p.ToLower())) { return $true }
+    }
+    return $false
+}
+
+function Split-Subcommands([string]$cmd) {
+    # Divide o comando em subcomandos por separadores: && || ; | newline
+    # Nao quebra dentro de strings (heuristica simples — suficiente para uso geral).
+    $parts = [System.Collections.ArrayList]::new()
+    $buf = ''
+    $inSingle = $false
+    $inDouble = $false
+    $i = 0
+    while ($i -lt $cmd.Length) {
+        $c = $cmd[$i]
+        $next = if ($i + 1 -lt $cmd.Length) { $cmd[$i + 1] } else { $null }
+        if ($c -eq "'" -and -not $inDouble) { $inSingle = -not $inSingle; $buf += $c; $i++; continue }
+        if ($c -eq '"' -and -not $inSingle) { $inDouble = -not $inDouble; $buf += $c; $i++; continue }
+        if (-not $inSingle -and -not $inDouble) {
+            if (($c -eq '&' -and $next -eq '&') -or ($c -eq '|' -and $next -eq '|')) {
+                $null = $parts.Add($buf); $buf = ''; $i += 2; continue
+            }
+            if ($c -eq ';' -or $c -eq '|' -or $c -eq "`n") {
+                $null = $parts.Add($buf); $buf = ''; $i++; continue
+            }
+        }
+        $buf += $c
+        $i++
+    }
+    if ($buf.Length -gt 0) { $null = $parts.Add($buf) }
+    return ,$parts
+}
+
+function Find-WriteToProtected([string]$subcmd) {
+    # Retorna o path protegido se este subcomando contem write verb + path; senao $null.
+    # Allowlist: subcomandos comecando com leitura (grep/cat/etc) NUNCA bloqueiam,
+    # mesmo que tenham strings como 'Set-Content' como argumento.
+    $trimmed = $subcmd.TrimStart()
+    $readOnlyPrefixes = @(
+        'grep', 'egrep', 'fgrep', 'rg', 'ag', 'cat', 'head', 'tail',
+        'less', 'more', 'ls', 'find', 'wc', 'stat', 'file', 'which',
+        'type', 'echo', 'printf',
+        'Get-Content', 'Get-ChildItem', 'Select-String', 'Test-Path',
+        'Resolve-Path', 'Get-Item', 'gci', 'gc', 'sls'
+    )
+    # Allowlist so vale se NAO houver redirect de escrita (> ou >>) no subcomando.
+    $hasRedirect = ($subcmd -match '>\s*[^\s|&]')
+    if (-not $hasRedirect) {
+        foreach ($pfx in $readOnlyPrefixes) {
+            if ($trimmed -match "^$([regex]::Escape($pfx))(\s|$)") { return $null }
+        }
+    }
+
+    $hasWriteVerb = $false
+    foreach ($v in $writeVerbPatterns) {
+        if ($subcmd -match $v) { $hasWriteVerb = $true; break }
+    }
+    if (-not $hasWriteVerb) { return $null }
+    $norm = ($subcmd -replace '\\', '/').ToLower()
+    foreach ($p in $protectedSubstrings) {
+        if ($norm.Contains($p.ToLower())) { return $p }
+    }
+    return $null
+}
+
+function Deny-Edit([string]$target, [string]$source) {
+    $reason = @"
+[OS GUARD] Arquivo protegido bloqueado: $target (via $source)
+
+Este arquivo faz parte do nucleo do AI Operating System.
+
+Para prosseguir, escolha UMA das opcoes:
+1. Criar ADR em .ai/memory/decisions.md justificando a mudanca + pedir confirmacao explicita do usuario no formato 'Confirmo alteracao em <path> - motivo: <razao>'.
+2. Bypass autorizado: o usuario cria o arquivo .claude/.unlock (basta existir). O guard fica inativo enquanto o arquivo existir.
+
+Apos a mudanca, recomenda-se remover .claude/.unlock para restaurar a protecao.
+"@
+    $response = @{
+        hookSpecificOutput = @{
+            hookEventName            = 'PreToolUse'
+            permissionDecision       = 'deny'
+            permissionDecisionReason = $reason
+        }
+    } | ConvertTo-Json -Depth 5 -Compress
+    Write-Output $response
+    exit 0
+}
+
+# Branch 1: Edit / Write / NotebookEdit — payload.tool_input.file_path
+if ($toolName -in @('Edit', 'Write', 'NotebookEdit')) {
+    $filePath = $payload.tool_input.file_path
+    if ($filePath -and (Test-ProtectedPath $filePath)) {
+        Deny-Edit -target $filePath -source $toolName
+    }
+}
+
+# Branch 2: Bash — split em subcomandos, bloqueia apenas se write verb + path protegido coexistirem no MESMO subcomando.
+if ($toolName -eq 'Bash') {
+    $cmd = $payload.tool_input.command
+    if ($cmd) {
+        $subs = Split-Subcommands $cmd
+        foreach ($s in $subs) {
+            $hit = Find-WriteToProtected $s
+            if ($hit) {
+                Deny-Edit -target $hit -source 'Bash'
+            }
+        }
+    }
+}
+
+# Aviso leve: editar codigo de producao sem ter consultado project-context.md
+if ($toolName -in @('Edit', 'Write', 'NotebookEdit')) {
+    $filePath = $payload.tool_input.file_path
+    if ($filePath) {
+        $markerPath = Join-Path $projectDir '.claude\.os-context-loaded'
+        $contextPath = Join-Path $projectDir '.ai\memory\project-context.md'
+        $isProductionEdit = ($filePath -notmatch '\.ai[\\/]') -and ($filePath -notmatch '(?i)(test|spec|\.md)$')
+        if ($isProductionEdit -and (Test-Path $contextPath) -and (-not (Test-Path $markerPath))) {
+            $warning = @{
+                hookSpecificOutput = @{
+                    hookEventName     = 'PreToolUse'
+                    additionalContext = '[OS WARNING] Voce esta editando codigo de producao mas project-context.md ainda nao foi consultado nesta sessao. Considere ler antes de prosseguir.'
+                }
+            } | ConvertTo-Json -Depth 5 -Compress
+            Write-Output $warning
+            exit 0
+        }
+    }
+}
+
+exit 0

package/ai/hooks/guard-edit.sh

@@ -0,0 +1,161 @@
+#!/usr/bin/env bash
+# PreToolUse hook (Unix) — matcher: Edit|Write|NotebookEdit|Bash
+# Bloqueia mudancas em arquivos protegidos do AI OS sem confirmacao explicita.
+# Para Bash, faz split em SUBCOMANDOS (&&, ||, ;, |, newline) e bloqueia
+# apenas o subcomando que contem write verb + path protegido juntos.
+# Override autorizado: criar .claude/.unlock (basta existir).
+set -euo pipefail
+
+PROJECT_DIR="${CLAUDE_PROJECT_DIR:-$(pwd)}"
+
+# Bypass via sentinela
+if [[ -f "$PROJECT_DIR/.claude/.unlock" ]]; then
+    exit 0
+fi
+
+PAYLOAD=$(cat)
+
+# Extractor JSON: node primeiro (mais robusto), depois python3 real (nao stub MS Store), depois grep.
+extract_field() {
+    local field="$1"
+    if command -v node &>/dev/null; then
+        echo "$PAYLOAD" | node -e "let s='';process.stdin.on('data',d=>s+=d).on('end',()=>{try{const o=JSON.parse(s);const f='$field';console.log(f==='tool_name'?o.tool_name||'':o.tool_input?.[f]||'')}catch{}})" 2>/dev/null && return 0
+    fi
+    if command -v python3 &>/dev/null && python3 -c "print('ok')" 2>/dev/null | grep -q '^ok$'; then
+        echo "$PAYLOAD" | python3 -c "import sys,json
+try:
+    d=json.load(sys.stdin)
+    f='$field'
+    print(d.get('tool_name','') if f=='tool_name' else d.get('tool_input',{}).get(f,''))
+except: pass" 2>/dev/null && return 0
+    fi
+    echo "$PAYLOAD" | grep -oE "\"$field\"[[:space:]]*:[[:space:]]*\"([^\"\\\\]|\\\\.)*\"" | sed 's/^"[^"]*"[[:space:]]*:[[:space:]]*"//; s/"$//' | head -1
+}
+
+TOOL_NAME=$(extract_field tool_name)
+
+PROTECTED=(
+    '.ai/rules/dont.md'
+    '.ai/contract.md'
+    '.ai/router.md'
+    '.ai/manifest.json'
+    '.ai/hooks/inject-os-reminder.ps1'
+    '.ai/hooks/inject-os-reminder.sh'
+    '.ai/hooks/guard-edit.ps1'
+    '.ai/hooks/guard-edit.sh'
+    '.ai/hooks/enforce-audit.ps1'
+    '.ai/hooks/enforce-audit.sh'
+    '.claude/settings.json'
+)
+
+WRITE_VERBS='(Set-Content|Out-File|Add-Content|Clear-Content|Tee-Object|New-Item|Remove-Item|Move-Item|Copy-Item|fs\.writeFile|fs\.appendFile|fs\.unlink|fs\.rm|fs\.rmdir|\brm[[:space:]]|\bmv[[:space:]]|\bcp[[:space:]]|\btee[[:space:]]|sed[[:space:]]+-i|>[[:space:]]*[^[:space:]|&]|>>[[:space:]]*[^[:space:]|&])'
+
+is_protected_path() {
+    local norm="${1//\\//}"
+    norm="$(echo "$norm" | tr '[:upper:]' '[:lower:]')"
+    for p in "${PROTECTED[@]}"; do
+        if [[ "$norm" == *"$p"* ]]; then
+            return 0
+        fi
+    done
+    return 1
+}
+
+# Retorna 0 (true) e ecoa o path se o subcomando tem write verb + path protegido.
+# Allowlist: subcomandos comecando com leitura (grep/cat/etc) NUNCA bloqueiam.
+READ_ONLY_PREFIXES='^[[:space:]]*(grep|egrep|fgrep|rg|ag|cat|head|tail|less|more|ls|find|wc|stat|file|which|type|echo|printf|Get-Content|Get-ChildItem|Select-String|Test-Path|Resolve-Path|Get-Item|gci|gc|sls)([[:space:]]|$)'
+
+find_write_to_protected() {
+    local sub="$1"
+    # Se o subcomando NAO contem redirect de escrita E comeca com prefixo read-only, nao bloqueia.
+    if ! echo "$sub" | grep -Eq '>[[:space:]]*[^[:space:]|&]'; then
+        if echo "$sub" | grep -Eq "$READ_ONLY_PREFIXES"; then
+            return 1
+        fi
+    fi
+    if ! echo "$sub" | grep -Eq "$WRITE_VERBS"; then
+        return 1
+    fi
+    local norm
+    norm=$(echo "${sub//\\//}" | tr '[:upper:]' '[:lower:]')
+    for p in "${PROTECTED[@]}"; do
+        if [[ "$norm" == *"$p"* ]]; then
+            echo "$p"
+            return 0
+        fi
+    done
+    return 1
+}
+
+# Split em subcomandos: usa awk com FS multi-char.
+# Separadores: && || ; | \n  (heuristica: nao quebra dentro de aspas — suficiente para uso geral)
+split_subcommands() {
+    local cmd="$1"
+    # Substitui separadores por \0 e divide.
+    echo "$cmd" | awk '
+    BEGIN { in_single=0; in_double=0; buf="" }
+    {
+        s = $0
+        for (i = 1; i <= length(s); i++) {
+            c  = substr(s, i, 1)
+            n  = (i < length(s)) ? substr(s, i+1, 1) : ""
+            if (c == "\047" && !in_double) { in_single = !in_single; buf = buf c; continue }
+            if (c == "\"" && !in_single)   { in_double = !in_double; buf = buf c; continue }
+            if (!in_single && !in_double) {
+                if ((c == "&" && n == "&") || (c == "|" && n == "|")) {
+                    print buf; buf = ""; i++; continue
+                }
+                if (c == ";" || c == "|") {
+                    print buf; buf = ""; continue
+                }
+            }
+            buf = buf c
+        }
+        if (length(buf) > 0) { print buf; buf = "" }
+    }'
+}
+
+deny() {
+    local target="$1"
+    local source="$2"
+    local REASON="[OS GUARD] Arquivo protegido bloqueado: $target (via $source). Este arquivo faz parte do nucleo do AI Operating System. Para prosseguir: 1) Criar ADR em .ai/memory/decisions.md + confirmacao explicita do usuario no formato 'Confirmo alteracao em <path> - motivo: <razao>'. OU 2) Bypass autorizado: usuario cria .claude/.unlock (basta existir; remover apos a mudanca para restaurar protecao)."
+    printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"deny","permissionDecisionReason":"%s"}}\n' "$REASON"
+    exit 0
+}
+
+case "$TOOL_NAME" in
+    Edit|Write|NotebookEdit)
+        FILE_PATH=$(extract_field file_path)
+        if [[ -n "$FILE_PATH" ]] && is_protected_path "$FILE_PATH"; then
+            deny "$FILE_PATH" "$TOOL_NAME"
+        fi
+        ;;
+    Bash)
+        CMD=$(extract_field command)
+        if [[ -n "$CMD" ]]; then
+            while IFS= read -r sub; do
+                [[ -z "$sub" ]] && continue
+                hit=$(find_write_to_protected "$sub" || true)
+                if [[ -n "$hit" ]]; then
+                    deny "$hit" "Bash"
+                fi
+            done < <(split_subcommands "$CMD")
+        fi
+        ;;
+esac
+
+# Aviso leve para edicao de producao sem ter consultado project-context.md
+if [[ "$TOOL_NAME" == "Edit" || "$TOOL_NAME" == "Write" || "$TOOL_NAME" == "NotebookEdit" ]]; then
+    FILE_PATH=$(extract_field file_path)
+    MARKER="$PROJECT_DIR/.claude/.os-context-loaded"
+    CONTEXT="$PROJECT_DIR/.ai/memory/project-context.md"
+    if [[ -n "$FILE_PATH" && -f "$CONTEXT" && ! -f "$MARKER" ]] && \
+       echo "$FILE_PATH" | grep -vqE '\.ai[\\/]' && \
+       echo "$FILE_PATH" | grep -vqiE '(test|spec|\.md)$'; then
+        WARN='[OS WARNING] Voce esta editando codigo de producao mas project-context.md ainda nao foi consultado nesta sessao. Considere ler antes de prosseguir.'
+        printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","additionalContext":"%s"}}\n' "$WARN"
+        exit 0
+    fi
+fi
+
+exit 0