@pathbit/agentdevkit 0.0.10 → 0.0.12

package/docs/maintainers/maintenance.md

@@ -28,10 +28,20 @@ O CI tem quatro perfis:
 | macOS / Node 24 | Portabilidade da CLI, arquivos e runtime. |
 | Linux / Node 26 | Smoke de compatibilidade. |
 
+O perfil macOS usa o runner padrão `macos-15-intel`. O label `macos-latest`
+usa ARM64 e pode ter filas diferentes; confira os [runners disponíveis][runners]
+antes de mudar a arquitetura. Provas locais devem informar a arquitetura usada.
+
 A distribuição real é testada uma vez no perfil completo. Os outros perfis
 validam seus riscos específicos. Execuções antigas da mesma referência podem
 ser canceladas quando substituídas, sem cancelar uma publicação em andamento.
 
+O workflow [Security tools smoke][security-ci] instala os três scanners com
+pins revisados em Linux, macOS e Windows. Depois analisa fixtures locais sem
+rede, com casos inseguros e corrigidos. Essa prova valida o funcionamento das
+ferramentas; não certifica a segurança de uma aplicação. Relatórios normalizados
+são guardados como artifacts, sem binários ou fontes das fixtures.
+
 `npm run verify` executa o perfil completo. `ci:portable` e `ci:smoke`
 executam os demais perfis localmente. `npm run test:examples` verifica os
 cenários em `examples/generated/` quando a mudança afeta a geração.
@@ -106,3 +116,5 @@ aprovado; uma aprovação de CI não substitui a instalação real pelo registro
 [ci]: https://github.com/pathbit/AgentDevKit/actions/workflows/ci.yml
 [release]: https://github.com/pathbit/AgentDevKit/actions/workflows/release.yml
 [package]: https://www.npmjs.com/package/@pathbit/agentdevkit
+[security-ci]: https://github.com/pathbit/AgentDevKit/actions/workflows/security-tools.yml
+[runners]: https://docs.github.com/en/actions/reference/runners/github-hosted-runners

package/docs/maintainers/packages.md

@@ -42,7 +42,7 @@ npx --registry=https://npm.pkg.github.com @pathbit/agentdevkit init
 ```
 
 Para repetir uma instalação, fixe a versão após o nome, como
-`@pathbit/agentdevkit@0.0.10`, nos dois destinos.
+`@pathbit/agentdevkit@0.0.12`, nos dois destinos.
 
 Acrescente `--agents codex,claude` para selecionar clientes, `--dry-run` para
 simular ou use `update`, `doctor` e `sync --check` no lugar de `init`.
@@ -89,7 +89,7 @@ Por padrão, uma tag publica nos dois destinos. Para completar o GitHub
 Packages de uma tag existente, preservando a release e o npm:
 
 ```console
-gh workflow run Release -f tag=v0.0.10 -F package_only=true -f registry=github
+gh workflow run Release -f tag=v0.0.12 -F package_only=true -f registry=github
 ```
 
 Se o artefato expirou, reexecute o CI original da tag antes da publicação.

package/docs/product/design.md

@@ -53,9 +53,15 @@ antigos sem escolha explícita mantêm esse comportamento.
 O instalador monta um plano, confere hashes e caminhos, apresenta conflitos e
 aplica mudanças com backup local. `--dry-run` não altera arquivos nem índice.
 
-Entradas humanas permanecem intactas. O kit cria suas próprias entradas quando
-faltam; na migração, separa seus blocos de texto humano. Nunca é possível
-ignorar somente um trecho de arquivo no Git.
+Entradas humanas recebem referências em um bloco delimitado do kit. O texto
+externo, frontmatter e nome existente são preservados; somente o hash do bloco
+é registrado. Alterações externas continuam permitidas; alterações dentro do
+bloco exigem revisão e não autorizam sobrescrever o arquivo com `--force`.
+Arquivos novos e integralmente gerados continuam com propriedade integral.
+Comandos TOML recebem a referência no valor de `prompt`, preservando as demais
+chaves. Configurações nativas fora desse escopo permanecem sob controle humano.
+Nunca é possível ignorar somente um trecho de arquivo no Git: arquivos mistos
+não entram nas exclusões do kit. Veja a [spec de integração][additive].
 
 Saídas identificadas são excluídas localmente do versionamento. O Git local
 usa `info/exclude`; fora de um repositório, a proteção fica no `.gitignore`
@@ -114,3 +120,4 @@ referência não comprova a execução da skill.
 [Recursos](../guides/resources.md)
 
 [clients]: ../../.pbai4devs/templates/clients/ADAPTERS.json
+[additive]: ../specs/additive-integration/SPEC.md

package/docs/product/prd.md

@@ -1,7 +1,7 @@
 ---
 description: Requisitos da distribuição portátil AgentDevKit.
 status: aprovado
-version: 0.0.10
+version: 0.0.12
 ---
 
 # PRD do AgentDevKit
@@ -43,6 +43,10 @@ extraído do projeto de origem como produto independente.
 | FR-021 | Inventariar documentos existentes antes de propor alterações. |
 | FR-022 | Complementar documentação sem substituir arquivos por templates. |
 | FR-023 | Provar o fluxo documental em projetos reais e em projeto vazio. |
+| FR-024 | Incluir procedimentos de segurança nas instalações do kit. |
+| FR-025 | Compor entregas com agentes, skills, comandos, scripts e regras. |
+| FR-026 | Auditar localmente com ferramentas OSS e relatórios sem segredos. |
+| FR-027 | Complementar instruções existentes sem substituir conteúdo humano. |
 
 Execuções repetidas devem ser idempotentes; a CLI oferece simulação e JSON.
 As instruções permanecem concisas, com detalhes opcionais em referências.

package/docs/product/roadmap.md

@@ -21,6 +21,8 @@ status: vigente
 | Preservação v0.0.8 | Auditoria e regressões | [Spec][robustness]. |
 | Coexistência v0.0.9 | Agentes, documentos e projetos reais | [Spec][coexistence]. |
 | Instalação nos dois registries v0.0.10 | Pacote e guias de pré-requisitos | [Spec][dual-install]. |
+| Segurança local v0.0.11 | Ferramentas e papéis especializados | [Spec][security]. |
+| Integração v0.0.12 | Preservação e propriedade por bloco | [Spec][additive]. |
 
 A primeira entrega segue a [spec v0.0.1](../specs/v0.0.1/SPEC.md), disponível
 na [release v0.0.1][release]. Os detalhes de mudanças estão no
@@ -44,3 +46,5 @@ comportamento existente, sem alterar a versão de uma release já publicada.
 [robustness]: ../specs/v0.0.8/SPEC.md
 [coexistence]: ../specs/v0.0.9/SPEC.md
 [dual-install]: ../specs/v0.0.10/SPEC.md
+[security]: ../specs/security-ecosystem/SPEC.md
+[additive]: ../specs/additive-integration/SPEC.md

package/docs/specs/README.md

@@ -16,6 +16,8 @@ description: Incrementos verificáveis do AgentDevKit.
 - [v0.0.9](v0.0.9/SPEC.md): coexistência e evolução documental sem perdas.
 - [Dois registries](dual-registry/SPEC.md): versão e bytes iguais no npm e GitHub.
 - [v0.0.10](v0.0.10/SPEC.md): release com instalação pelos dois registries e pré-requisitos.
+- [Ecossistema de segurança](security-ecosystem/SPEC.md): fluxos e scanners locais.
+- [Integração sem substituição][additive]: acréscimos em arquivos existentes.
 
 Cada incremento vincula requisitos, critérios, testes e evidências locais.
 
@@ -24,3 +26,5 @@ projeto, siga o [fluxo](../guides/workflow.md) e use os
 [modelos compartilhados](../../.pbai4devs/templates/README.md).
 
 [Wiki](../README.md) · [Roadmap](../product/roadmap.md)
+
+[additive]: additive-integration/SPEC.md

package/docs/specs/additive-integration/README.md

@@ -0,0 +1,9 @@
+---
+description: Acréscimos seguros em instruções e pastas existentes.
+---
+
+# Integração sem substituição
+
+A [spec](SPEC.md) define blocos gerenciados, preservação humana e suas provas.
+
+[Specs](../README.md) · [Instalação](../../guides/installation.md)

package/docs/specs/additive-integration/SPEC.md

@@ -0,0 +1,53 @@
+---
+description: Complementar instruções existentes sem substituir conteúdo humano.
+status: aprovado
+version: 0.0.12
+---
+
+# Integração sem substituição
+
+## Objetivo
+
+Ao instalar, atualizar ou sincronizar, acrescentar referências do AgentDevKit
+aos arquivos de instruções existentes. Preservar conteúdo, metadados, nomes,
+permissões e índice Git do usuário, inclusive em colisões de nomes.
+
+## Contrato
+
+- Entradas raiz existentes recebem um bloco curto; aliases únicos como
+  `agents.md` são reutilizados sem criar uma segunda entrada.
+- Skills, agentes, regras e comandos Markdown existentes recebem só uma
+  referência ao hub. O frontmatter humano não é substituído.
+- Comandos Gemini existentes recebem a referência dentro de `prompt`, em
+  TOML válido. Sintaxe não suportada é preservada e informada.
+- O estado registra a propriedade do bloco, nunca do arquivo humano inteiro.
+- Atualizações preservam edições humanas fora do bloco. Marcadores ambíguos
+  ou blocos adulterados impedem substituição, inclusive com `--force`.
+- Remover um recurso gerenciado remove somente sua contribuição comprovada.
+- Arquivos humanos continuam sujeitos às escolhas de Git do próprio projeto;
+  o kit ignora seus derivados por arquivo, não a pasta inteira do cliente.
+- Links simbólicos não são seguidos. Configurações externas ao escopo de
+  instruções não são reformatadas nem mescladas arbitrariamente.
+
+## Critérios de aceite
+
+| ID | Resultado observável |
+| --- | --- |
+| AC-001 | Entradas raiz humanas recebem a referência e preservam seus bytes. |
+| AC-002 | Colisões Markdown preservam frontmatter e texto, com bloco único. |
+| AC-003 | Repetições são idempotentes; edições fora do bloco são preservadas. |
+| AC-004 | Blocos alterados, ambiguidades e links não causam perda de dados. |
+| AC-005 | Retirada de bloco preserva texto, permissões e índice humano. |
+| AC-006 | TOML mantém semântica humana e referência válida no prompt. |
+| AC-007 | Git não passa a ignorar arquivos humanos por propriedade parcial. |
+| AC-008 | Pacote real, regressões, maturidade e revisão independente passam. |
+
+## Validação
+
+Fixtures existentes incluem frontmatter próprio, caixa diferente, BOM, CRLF,
+ausência de newline final, alterações posteriores, arquivos já staged e
+comandos estruturados. Testar perda de origem, rollback, `--force`, simulação,
+`doctor`, `sync --check` e instalação do pacote gerado.
+
+Testes são versionados. Backups, snapshots e relatórios ficam ignorados em
+`.agent-tests/` ou `tmp/`; não alterar projetos consumidores nesta entrega.

package/docs/specs/security-ecosystem/README.md

@@ -0,0 +1,9 @@
+---
+description: Fluxos agênticos e segurança local do AgentDevKit.
+---
+
+# Ecossistema de segurança
+
+[Spec](SPEC.md): integrar recursos e scanners locais com provas de funcionamento.
+
+[Specs](../README.md) · [Segurança](../../guides/security.md)

package/docs/specs/security-ecosystem/SPEC.md

@@ -0,0 +1,53 @@
+---
+description: Recursos agênticos integrados e verificações locais de segurança.
+status: aprovado
+version: 0.0.11
+---
+
+# Ecossistema de segurança local
+
+## Objetivo
+
+Instalar procedimentos de segurança com o kit e conectar skills, comandos,
+agentes, regras, scripts e ferramentas em fluxos completos. Documentar a
+responsabilidade de cada recurso e usar análise local open source, sem conta
+ou pagamento obrigatório. Atualizar o talquee-ai-router pelo npm para 0.0.10
+preservando seu conteúdo e configuração.
+
+## Contrato
+
+- Skills explicam procedimentos; agentes assumem uma tarefa e sua entrega.
+- Comandos organizam entradas e etapas; scripts executam ações determinísticas.
+- Regras orientam contextos; ferramentas fornecem capacidades locais.
+- A instalação inclui fontes de segurança e apontamentos dos clientes escolhidos.
+- Scanners são instalados explicitamente, sem iniciar serviços.
+- Downloads públicos são separados da análise offline, com pins e integridade.
+- Ausência de ferramenta, base ou prova nunca equivale a uma auditoria aprovada.
+- Segredos, código e relatórios permanecem locais.
+- Scanners não substituem testes de autorização, isolamento e regras de negócio.
+- Preservar histórico e personalizações nos dois repositórios.
+- Distribuir os novos recursos em 0.0.11, mantendo o router fixado em 0.0.10.
+
+## Critérios de aceite
+
+| ID | Resultado observável |
+| --- | --- |
+| AC-001 | Instalação inclui skills, regras, comandos e perfis de segurança. |
+| AC-002 | Docs explicam componentes e fluxos conectados, com casos de uso. |
+| AC-003 | Três scanners OSS instalam, atualizam e verificam os pins locais. |
+| AC-004 | Auditoria offline detecta fixtures inseguras e diferencia falhas. |
+| AC-005 | Relatórios não expõem segredos e permanecem ignorados pelo Git. |
+| AC-006 | Curadoria registra fontes, licenças, limites e correções do artigo. |
+| AC-007 | Router em 0.0.10 preserva arquivos, índice, idioma e clientes. |
+| AC-008 | Regressões, pacote real, espelhos e revisão independente passam. |
+
+## Validação
+
+Verificar criação e descoberta de recursos em instalações novas e existentes.
+Executar scanners reais contra casos seguros e inseguros locais, com bases
+controladas e sem chamadas a serviços de análise. Testar downloads, hashes,
+links, rollback, dados ausentes, erros de scanner e saídas redigidas.
+Comparar snapshots do router antes e depois da atualização pelo npm.
+
+Código de testes é versionado; bases, binários, relatórios e snapshots ficam
+em `.agent-tests/`, `.local/` ou `tmp/`, ignorados pelo Git.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pathbit/agentdevkit",
-  "version": "0.0.10",
+  "version": "0.0.12",
   "description": "Shared skills, specifications and workflows for AI coding agents.",
   "type": "module",
   "license": "MIT",