@jaimevalasek/aioson 1.7.0 → 1.8.0

package/template/.aioson/agents/validator.md

@@ -0,0 +1,69 @@
+# Agente @validator
+
+> ⚡ **ACTIVATED** — Você está operando como @validator. Sua missão é validar tecnicamente o output do implementador contra o contrato de sucesso.
+
+## Missão
+Atuar como o "Validador" no Padrão Nautilus. Sua única responsabilidade é verificar se os critérios binários definidos no `harness-contract.json` foram atendidos. Você é o gatekeeper final antes de uma feature ser marcada como concluída.
+
+## Restrições de Contexto (Obrigatório)
+Para garantir imparcialidade e evitar alucinações de continuidade, você opera em um **sandbox de contexto estrito**:
+
+1. **Lê (Somente):**
+   - `.aioson/plans/{slug}/harness-contract.json` (O Contrato)
+   - `.aioson/plans/{slug}/progress.json` (Estado Atual)
+   - Arquivos explicitamente listados em `progress.json.completed_steps`
+   - Output de ferramentas de diagnóstico (Linter, Test Runners, Compiladores)
+2. **NUNCA lê:**
+   - Histórico de conversa de outros agentes (@dev, @analyst, @architect)
+   - PRDs, Requirements ou Architecture (seu foco é o contrato binário, não a visão de produto)
+   - Código de outras features não relacionadas ao contrato atual
+3. **Comportamento:**
+   - Nunca implemente código. Você apenas observa e reporta.
+   - Nunca sugira refatorações estéticas ou melhorias que não estejam no contrato.
+   - Se um critério falhar, forneça a razão técnica exata (ex: "Arquivo X não encontrado" ou "Erro de sintaxe na linha Y").
+
+## Protocolo de Execução (RF-VAL)
+
+### Passo 1: Carregamento
+Localize o `harness-contract.json` para a feature atual. Identifique os critérios `binary: true`.
+
+### Passo 2: Verificação Determinística
+Execute (ou solicite a execução) de ferramentas locais para cada critério:
+- `ls -l {path}` para existência de arquivos.
+- `cat {path}` para validar padrões ou conteúdo.
+- `npm test` ou equivalente para critérios de execução.
+
+### Passo 3: Verificação Semântica
+Para critérios que exigem compreensão (ex: "API segue o padrão REST"), analise o código entregue contrastando exclusivamente com o que o contrato exige.
+
+### Passo 4: Geração de Veredicto
+Seu output deve ser **EXCLUSIVAMENTE** um objeto JSON estruturado para ser parseado pela máquina. Não adicione preâmbulos ou explicações fora do JSON.
+
+## Output Format (JSON)
+
+```json
+{
+  "phase": {N},
+  "validation_at": "{ISO-8601}",
+  "results": [
+    {
+      "id": "{C1, C2...}",
+      "passed": {true|false},
+      "reason": {null | "mensagem técnica do erro"}
+    }
+  ],
+  "overall_score": {0 | 1},
+  "ready_for_done_gate": {true | false}
+}
+```
+
+- `overall_score`: `1` se TODOS os critérios obrigatórios passaram; `0` caso contrário.
+- `ready_for_done_gate`: `true` se a feature pode seguir para o status `done`.
+
+## Interação
+Após emitir o JSON, encerre a sessão imediatamente. Você é um processo de curta duração.
+
+---
+## ▶ Próximo passo
+O resultado será gravado no `progress.json` pelo gateway. Ative o agente de volta (@dev) para correção ou siga para o fechamento da feature.
+---

package/template/.aioson/brains/scripts/query.js

@@ -58,7 +58,11 @@ if (tags.length > 0) {
 // --- Load nodes ---
 let nodes = [];
 for (const brain of brainFiles) {
-  const brainPath = path.join(BRAINS_DIR, '..', brain.path);
+  const brainPath = path.isAbsolute(brain.path)
+    ? brain.path
+    : brain.path.startsWith('.aioson/brains/')
+      ? path.join(BRAINS_DIR, '..', '..', brain.path)
+      : path.join(BRAINS_DIR, brain.path);
   if (!fs.existsSync(brainPath)) {
     process.stderr.write(`Warning: brain file not found: ${brainPath}\n`);
     continue;

package/template/.aioson/config/autonomy-protocol.json

@@ -0,0 +1,43 @@
+{
+  "version": "1.0",
+  "global_mode": "guarded",
+  "tools": {
+    "codex": {
+      "mode": "trusted",
+      "fallback_mode": "guarded",
+      "shell_whitelist": ["git *", "npm *", "npx *", "node *", "aioson *"],
+      "shell_blacklist": ["rm -rf /", "curl * | sh", "*>*"],
+      "aioson_whitelist": ["workflow:next", "workflow:heal", "commit:prepare", "git:guard", "runtime:emit", "live:handoff"],
+      "requires_tty": false,
+      "max_auto_retries": 3
+    },
+    "claude": {
+      "mode": "trusted",
+      "fallback_mode": "guarded",
+      "shell_whitelist": ["git *", "npm *", "npx *", "node *", "aioson *"],
+      "shell_blacklist": ["rm -rf /", "curl * | sh", "*>*"],
+      "aioson_whitelist": ["workflow:next", "workflow:heal", "commit:prepare", "git:guard", "runtime:emit", "live:handoff"],
+      "requires_tty": false,
+      "max_auto_retries": 3
+    },
+    "gemini": {
+      "mode": "guarded",
+      "fallback_mode": "guarded",
+      "shell_whitelist": ["git status", "git log", "npm test"],
+      "aioson_whitelist": ["workflow:next"],
+      "requires_tty": true,
+      "max_auto_retries": 1
+    },
+    "opencode": {
+      "mode": "guarded",
+      "fallback_mode": "abort",
+      "shell_whitelist": [],
+      "aioson_whitelist": ["workflow:next"],
+      "requires_tty": true,
+      "max_auto_retries": 0
+    }
+  },
+  "agents": {
+    "committer": { "max_mode": "guarded" }
+  }
+}

package/template/.aioson/config.md

@@ -48,7 +48,8 @@ Quando o agente perceber que está próximo do threshold:
 - `framework`
 - `framework_installed` (boolean) — `true` means the framework was detected in the workspace; downstream agents skip installation commands. `false` means it was not detected; agents must include installation steps before any implementation.
 - `classification`
-- `conversation_language` (BCP-47, for example `en`, `pt-BR`)
+- `interaction_language` (BCP-47, for example `en`, `pt-BR`)
+- `conversation_language` (legacy compatibility alias; keep synchronized with `interaction_language`)
 - `aioson_version`
 
 Optional UI context fields:
@@ -63,6 +64,7 @@ Allowed `project_type` values:
 - `site`
 - `script`
 - `dapp`
+- `desktop_app`
 
 Optional Web3 context fields (recommended for `project_type=dapp`):
 - `web3_enabled` (boolean)
@@ -205,6 +207,19 @@ Agents load a doc only when its `description` matches the current task or when a
 
 **Key principle:** docs persist across sessions. A refactoring plan saved here will be available to any future agent that works on the same area — no need to re-explain context.
 
+### Code governance (`.aioson/design-docs/`)
+
+Persistent code-structure governance surfaced by `aioson preflight` and loaded on demand by agents. These files are project-local: installed once, preserved on update, and restorable with `aioson doctor --fix` if missing.
+
+Default governance files:
+- `folder-structure.md`
+- `componentization.md`
+- `code-reuse.md`
+- `naming.md`
+- `file-size.md`
+
+**When to use:** folder structure, naming, reuse, component boundaries, file-size thresholds, and maintainability constraints.
+
 ### Design docs (`.aioson/context/design-doc.md`)
 
 Living decision documents that bridge discovery and implementation. Produced by `@discovery-design-doc`.
@@ -219,16 +234,31 @@ agents: [dev, architect]   # empty [] = all agents load it
 
 **Design-doc vs PRD — when to use each:**
 
-| | PRD (`prd.md`) | Design doc (`design-doc.md`) |
-|---|---|---|
-| **Produced by** | `@product` | `@discovery-design-doc` |
-| **Focus** | What and why — vision, users, problem, features | How — technical flows, decisions, risks, slices |
-| **Audience** | All agents | Technical agents (dev, architect, qa) |
-| **Lifecycle** | Written once, enhanced by @pm | Living document, updated as decisions are made |
-| **When to create** | Every project/feature | Complex features needing technical clarity |
+| | PRD (`prd.md`) | Code governance (`.aioson/design-docs/`) | Design doc (`design-doc.md`) |
+|---|---|---|---|
+| **Produced by** | `@product` | Installer + project team | `@discovery-design-doc` |
+| **Focus** | What and why — vision, users, problem, features | Structural code quality rules | How — technical flows, decisions, risks, slices |
+| **Audience** | All agents | Agents doing structural planning or implementation | Technical agents (dev, architect, qa) |
+| **Lifecycle** | Written once, enhanced by @pm | Stable, edited when conventions change | Living document, updated as decisions are made |
+| **When to create** | Every project/feature | Installed by default | Complex features needing technical clarity |
 
 A project can have both: the PRD defines the product; the design-doc defines the approach. For simple features (MICRO), only the PRD may be needed.
 
+### Bootstrap (`.aioson/context/bootstrap/`)
+
+Semantic knowledge cache that gives agents instant understanding of the system without reading the codebase. Generated by `@discover`.
+
+| File | Content | Loaded by |
+|------|---------|-----------|
+| `what-is.md` | System identity, users, value proposition | `@product`, `@analyst` |
+| `how-it-works.md` | Architecture, modules, data flow, integrations | `@dev`, `@architect` |
+| `what-it-does.md` | Features, business rules, user workflows | `@product`, `@analyst` |
+| `current-state.md` | Implementation status, tech debt, recent changes | `@dev`, `@qa` |
+
+**When to use:** run `@discover` once after setup, and re-run when significant changes accumulate. Agents read bootstrap files at session start for instant context.
+
+**Key difference from `discovery.md`:** `discovery.md` is a technical scan (routes, entities, structure). Bootstrap is semantic (meaning, purpose, business rules). They complement each other.
+
 ## Skills
 
 AIOSON ships three types of skills in `.aioson/skills/`:
@@ -373,10 +403,8 @@ When the same setting exists in multiple tiers, the lower tier wins (local > pro
 Until the user tier is implemented in the CLI, use `CLAUDE.local.md` for personal
 preferences that should not affect other team members.
 
-## Agent locale packs
-- Localized agent prompts are stored in `.aioson/locales/<locale>/agents/`.
-- Active runtime prompts are in `.aioson/agents/`.
-- Built-in locale packs: `en`, `pt-BR`, `es`, `fr`.
-- Apply locale pack using:
-  - `aioson locale:apply` (reads `conversation_language` from context)
-  - `aioson locale:apply --lang=pt-BR` (manual override, also accepts `en`, `es`, `fr`)
+## Agent language model
+- Canonical agent prompts are stored only in `.aioson/agents/` and written in English.
+- User-facing communication is controlled by `interaction_language`.
+- `conversation_language` remains as a compatibility alias for older projects.
+- Use `aioson locale:apply` to restore canonical prompts and synchronize the chosen `interaction_language`.

package/template/.aioson/constitution.md

@@ -1,33 +1,36 @@
----
-version: 1.0.0
-ratified: 2026-04-04
-last_amended: 2026-04-04
----
-
-# AIOSON Constitution
-
-> Principles that govern all agents, all classifications, all sessions.
-> Every agent may cite these articles. No agent may override them.
-
-## Article I — Spec First
-Features begin as specifications, not code. Implementation without a spec artifact is exploration, not development.
-
-## Article II — Right-Sized Process
-MICRO, SMALL, and MEDIUM must not receive the same process depth. Applying MEDIUM ceremony to a MICRO project wastes more than it protects.
-
-## Article III — Observable Work
-Important agent actions leave visible artifacts or runtime signals. Work that exists only in conversation history is work that can be lost.
-
-## Article IV — Testable Behavior
-Acceptance criteria must be independently verifiable. "Works correctly" is not a criterion. "Returns 403 when user A accesses user B's resource" is.
-
-## Article V — Clean Handoffs
-Artifacts must be self-contained enough for the next agent to start without re-reading the full discovery chain. If the next agent needs to ask "where do I start?", the handoff failed.
-
-## Article VI — Simplicity Over Ceremony
-Do not add layers, files, or workflows unless they reduce downstream ambiguity. Three similar lines of code is better than a premature abstraction. One well-written spec is better than five thin artifacts.
-
-## Governance
-- Amendments require explicit user approval
-- Articles are numbered, not named — never renumber existing articles
-- New articles are appended, never inserted
+---
+version: 1.1.0
+ratified: 2026-04-04
+last_amended: 2026-04-28
+---
+
+# AIOSON Constitution
+
+> Principles that govern all agents, all classifications, all sessions.
+> Every agent may cite these articles. No agent may override them.
+
+## Article I — Spec First
+Features begin as specifications, not code. Implementation without a spec artifact is exploration, not development.
+
+## Article II — Right-Sized Process
+MICRO, SMALL, and MEDIUM must not receive the same process depth. Applying MEDIUM ceremony to a MICRO project wastes more than it protects.
+
+## Article III — Observable Work
+Important agent actions leave visible artifacts or runtime signals. Work that exists only in conversation history is work that can be lost.
+
+## Article IV — Testable Behavior
+Acceptance criteria must be independently verifiable. "Works correctly" is not a criterion. "Returns 403 when user A accesses user B's resource" is.
+
+## Article V — Clean Handoffs
+Artifacts must be self-contained enough for the next agent to start without re-reading the full discovery chain. If the next agent needs to ask "where do I start?", the handoff failed.
+
+## Article VI — Simplicity Over Ceremony
+Do not add layers, files, or workflows unless they reduce downstream ambiguity. Three similar lines of code is better than a premature abstraction. One well-written spec is better than five thin artifacts.
+
+## Article VII — Zero Trust by Default
+Security is a baseline, not a feature. Every technical agent (`@analyst`, `@architect`, `@dev`, `@qa`) must consume the security baseline declared in `.aioson/rules/security-baseline.md`, which defines the controls, severities, evidence and per-classification policy (MICRO advisory, SMALL scan, MEDIUM audit-blocking on open High/Critical findings). Controls carry stable IDs (`SEC-SBD-01`..`SEC-SBD-08`) so requirements, conformance and findings can reference them without prose drift. Agents may not silently weaken, rename or skip a control — deviations require an explicit decision recorded in the feature spec.
+
+## Governance
+- Amendments require explicit user approval
+- Articles are numbered, not named — never renumber existing articles
+- New articles are appended, never inserted

package/template/.aioson/context/design-doc.md

@@ -0,0 +1,136 @@
+---
+title: "Design Governance — Code Organization Rules"
+scope: "project"
+agents: []
+updated: "2026-04-12"
+---
+
+# Design Doc — Code Organization
+
+> Este arquivo define as regras de organização de código para este projeto.
+> É carregado obrigatoriamente por `@dev` e `@deyvin` antes de qualquer implementação.
+> É gerado/atualizado por `@discovery-design-doc` durante o gate pré-dev.
+> Agentes podem enriquecer este arquivo com padrões descobertos durante implementação — nunca remover seções.
+
+---
+
+## Organização de pastas
+
+**Princípio:** estrutura hierárquica semântica — cada pasta representa uma responsabilidade, não uma coleção aleatória de arquivos.
+
+**Regras:**
+- Máximo 3 níveis de profundidade antes de reavaliar a estrutura. Se precisar de mais, a responsabilidade provavelmente deve ser um módulo separado.
+- Singular para entidade única ou responsabilidade específica: `command/`, `service/`, `handler/`, `util/`
+- Plural para coleções de itens do mesmo tipo: `commands/`, `services/`, `handlers/`, `utils/`
+- Kebab-case para todos os nomes de pasta: `squad-dashboard/`, `context-cache/`, `runner/`
+- Nunca misturar estilos dentro de um mesmo nível de diretório
+
+**Padrão de agrupamento:**
+```
+src/
+  commands/       ← todos os handlers de CLI (um arquivo por comando)
+  lib/            ← lógica reutilizável sem dependência de CLI
+    {domínio}/    ← agrupado por domínio (genomes/, squads/, store/)
+  squad/          ← lógica específica do sistema de squads
+  runner/         ← lógica de execução de planos
+  i18n/           ← internacionalização
+    messages/     ← arquivos de tradução por locale
+```
+
+**Evitar:**
+- Pastas genéricas como `misc/`, `stuff/`, `temp/`, `old/`
+- Arquivos soltos na raiz de `src/` que pertencem a um domínio específico
+- Uma pasta com um único arquivo (exceto `index.js` de módulo público)
+
+---
+
+## Componentização
+
+**Quando extrair um componente ou módulo separado:**
+- A lógica aparece em 2+ lugares diferentes → extrair para `lib/` ou utilitário compartilhado
+- O arquivo está se aproximando de 300 linhas de lógica pura (excluindo comentários e linhas em branco)
+- A responsabilidade pode ser descrita em uma frase curta e distinta
+- O código pode ser testado de forma independente
+
+**Quando manter inline:**
+- Lógica usada em único lugar e com menos de ~50 linhas
+- Abstração prematura sem segundo uso confirmado
+- Extração criaria um arquivo de uma única função trivial
+
+**Responsabilidade única:**
+- Um arquivo = uma responsabilidade principal
+- Funções auxiliares de suporte à responsabilidade principal podem coexistir no mesmo arquivo
+- Funções auxiliares usadas em 2+ arquivos → mover para `utils.js` ou módulo dedicado
+
+---
+
+## Reuso
+
+**Antes de criar qualquer arquivo novo:**
+1. Verificar se `src/utils.js` já resolve o problema
+2. Verificar se existe módulo em `src/lib/` com responsabilidade próxima
+3. Verificar se o padrão existe em algum `src/commands/*.js` similar
+
+**Hierarquia de reuso:**
+1. Função utilitária existente em `src/utils.js`
+2. Módulo de lib em `src/lib/{domínio}/`
+3. Helper local no próprio arquivo (se uso único)
+4. Novo arquivo somente se nenhuma das opções acima servir
+
+**Composição sobre duplicação:**
+- Nunca copiar-colar blocos de código entre arquivos — extrair para função nomeada
+- Se dois comandos CLI têm lógica similar, o ponto comum vai para `src/lib/`
+- Se dois arquivos importam a mesma sequência de dependências, criar uma factory ou inicializador
+
+---
+
+## Tamanho de arquivo
+
+**Guideline:**
+- **< 300 linhas** — ideal. Arquivo focado e coeso.
+- **300–500 linhas** — aceitável. Monitorar crescimento.
+- **> 500 linhas** — ⚠ alerta. `@dev` e `@deyvin` devem propor split antes de continuar.
+
+**Protocolo de alerta (implementado por @dev e @deyvin):**
+Ao estimar que um arquivo resultante terá mais de 500 linhas:
+1. Emitir alerta com estimativa
+2. Listar 2–3 alternativas concretas de extração ou componentização
+3. Aguardar confirmação antes de continuar (`@dev`) ou prosseguir após 1 turno sem resposta (`@deyvin` pair mode)
+
+**O alerta nunca é bloqueante** — é uma pausa para pensar, não um impedimento.
+
+**Estratégias de split comuns:**
+- Extrair funções de validação para `validate-{domínio}.js`
+- Extrair helpers de formatação para `format-{domínio}.js`
+- Separar lógica de leitura/escrita de arquivo em módulo de I/O
+- Quebrar comando CLI grande em command handler + business logic em `lib/`
+
+**Exceções documentadas:** arquivos de mensagens i18n, fixtures de teste e arquivos gerados automaticamente não contam para o guideline.
+
+---
+
+## Nomeclatura
+
+**Arquivos:**
+- kebab-case para todos os arquivos: `squad-dashboard.js`, `context-writer.js`
+- Prefixo de domínio quando dentro de pasta flat: `squad-plan.js`, `squad-status.js` (dentro de `commands/`)
+- Sem sufixos genéricos como `helper`, `manager`, `handler` quando o nome do domínio já é claro
+
+**Por camada:**
+| Camada | Convenção | Exemplo |
+|--------|-----------|---------|
+| CLI commands | `{namespace}-{action}.js` | `squad-deploy.js`, `workflow-next.js` |
+| Lib / domain logic | `{responsabilidade}.js` | `context-compactor.js`, `learning-extractor.js` |
+| Utils compartilhados | `{tipo}-{domínio}.js` ou `utils.js` | `genome-format.js`, `utils.js` |
+| Entry points de módulo | `index.js` | `src/i18n/index.js` |
+| Configuração | `{nome}.config.js` ou `constants.js` | `constants.js` |
+
+**Variáveis e funções (JavaScript):**
+- camelCase: `contextPackage`, `featureSlug`, `runtimeStore`
+- Constantes globais: SCREAMING_SNAKE_CASE — `MAX_RETRIES`, `DEFAULT_TIMEOUT`
+- Funções: verbo + substantivo — `loadContext()`, `parseManifest()`, `emitEvent()`
+- Booleanos: prefixo `is`, `has`, `should` — `isReady`, `hasErrors`, `shouldRetry`
+
+**Banco de dados (SQLite):**
+- snake_case para tabelas e colunas: `agent_runs`, `session_key`, `started_at`
+- Tabelas no plural: `agent_runs`, `runtime_logs`

package/template/.aioson/context/project-map.md

@@ -0,0 +1,57 @@
+---
+agents: [dev, architect, ux-ui, qa, tester, committer]
+---
+
+# Canonical Project Map
+
+> When the user mentions a directory, resolve it using this map before creating files.
+> If ambiguous, confirm the exact path with the user.
+
+## Root-level directories
+
+| Intent | Canonical path | Notes |
+|---|---|---|
+| `docs/` (root) | `docs/` | Project documentation for humans. NOT `.aioson/docs/`. |
+| `plans/` | `plans/` | Pre-production research and plans. |
+| `prds/` | `prds/` | Product requirement drafts (not active PRDs). |
+| `src/` | `src/` | Source code. |
+| `tests/` | `tests/` | Test files. |
+| `scripts/` | `scripts/` | Utility scripts. |
+| `bin/` | `bin/` | CLI entry points. |
+| `changelogs/` | `changelogs/` | Release notes and changelogs. |
+
+## AIOSON-managed directories
+
+| Intent | Canonical path | Notes |
+|---|---|---|
+| `.aioson/` | `.aioson/` | Framework context and runtime. |
+| `agents/` | `.aioson/agents/` | Agent prompt files. |
+| `context/` | `.aioson/context/` | Workflow state, handoffs, specs. |
+| `docs/` (aioson) | `.aioson/docs/` | Private docs loaded on-demand by agents. |
+| `rules/` | `.aioson/rules/` | Project-specific rules for agents. |
+| `design-docs/` | `.aioson/design-docs/` | Code governance docs. |
+| `plans/` (feature) | `.aioson/plans/{slug}/` | Feature plans and harness contracts. |
+| `runtime/` | `.aioson/runtime/` | SQLite telemetry and dashboard data. |
+| `backups/` | `.aioson/backups/` | Auto-generated backups. |
+| `skills/` | `.aioson/skills/` | Design, static and dynamic skills. |
+| `installed-skills/` | `.aioson/installed-skills/` | Third-party installed skills. |
+
+## Context files (must live in `.aioson/context/`)
+
+| File | Canonical path |
+|---|---|
+| `project.context.md` | `.aioson/context/project.context.md` |
+| `prd.md` | `.aioson/context/prd.md` |
+| `spec.md` | `.aioson/context/spec.md` |
+| `last-handoff.json` | `.aioson/context/last-handoff.json` |
+| `workflow.state.json` | `.aioson/context/workflow.state.json` |
+| `project-pulse.md` | `.aioson/context/project-pulse.md` |
+| `dev-state.md` | `.aioson/context/dev-state.md` |
+| `commit-prep.json` | `.aioson/context/commit-prep.json` |
+
+## Path rules
+
+1. **When the user says `/docs/`, they mean the project root `docs/` folder**, not `.aioson/docs/`.
+2. **When the user specifies a target directory, confirm the exact path** before creating files.
+3. **Never create bootstrap or template files in the project root** unless explicitly asked. Default to `.aioson/context/` for framework artifacts.
+4. **Never overwrite `.gitignore`**, `README.md`, or existing config files unless explicitly asked. Append or modify the targeted item only.

package/template/.aioson/design-docs/code-reuse.md

@@ -0,0 +1,48 @@
+---
+description: "DRY principles, reuse hierarchy, and composition patterns"
+scope: "governance"
+agents: []
+---
+
+# Code Reuse — Governance Rules
+
+> Loaded automatically by @dev and @deyvin. Override per-project via `.aioson/rules/`.
+
+## Before creating any new file
+
+Always verify in this order:
+
+1. Does a shared utility already solve this? (check `utils.js`, `utils/`, `helpers/`, `shared/`)
+2. Does a domain module in `lib/`, `services/`, or `lib/` already own this responsibility?
+3. Does a similar existing file already do something close enough to extend?
+
+Create a new file only if none of the above applies.
+
+## Reuse hierarchy
+
+1. **Existing shared utility** — call it, do not reimplement
+2. **Domain module** — if the logic is domain-specific, extend the right module
+3. **Inline helper** — acceptable if single use and under ~50 lines
+4. **New file** — only when no existing location is appropriate
+
+## Composition over duplication
+
+- Never copy-paste code blocks between files — extract to a named function instead
+- If two modules import the same sequence of dependencies, consider a factory or initializer
+- If the same validation logic appears in 3+ places, it belongs in a shared validator
+- If two commands share a pattern for reading + transforming + writing, extract the pipeline
+
+## DRY with pragmatism
+
+DRY applies to **logic**, not to **structure**:
+
+- Two functions that look similar but serve different domain concepts should stay separate
+- Merging them to reduce lines often creates the wrong abstraction
+- Duplicating a string or constant is worse than a duplicate variable — always use named constants
+- Small, isolated duplication is sometimes better than a shared dependency that couples unrelated modules
+
+## When NOT to reuse
+
+- When the shared abstraction introduces coupling between unrelated modules
+- When the reused code would need flags or conditionals to serve a new caller — that signals divergence, not reuse
+- When the only shared thing is syntax, not semantics

package/template/.aioson/design-docs/componentization.md

@@ -0,0 +1,47 @@
+---
+description: "When and how to extract components, modules, and abstractions"
+scope: "governance"
+agents: []
+---
+
+# Componentization — Governance Rules
+
+> Loaded automatically by @dev and @deyvin. Override per-project via `.aioson/rules/`.
+
+## When to extract
+
+Extract a component, module, or function when ANY of these is true:
+
+1. **Duplication** — the same logic appears in 2 or more different places
+2. **Size** — a file is approaching 300 lines of pure logic (excluding comments and blank lines)
+3. **Testability** — the piece of logic can be tested in isolation from the rest
+4. **Description** — the responsibility can be stated in one short, specific sentence
+
+## When to keep inline
+
+Keep logic inline when ALL of these are true:
+
+- Used in exactly one place
+- Under ~50 lines
+- Extracting it would create a file with a single trivial function
+- No second confirmed use case exists
+
+## Single responsibility
+
+- One file = one primary responsibility
+- Supporting helper functions for that primary responsibility may coexist in the same file
+- Helper functions used in 2+ files → move to a shared utility or dedicated module
+
+## Avoid premature abstraction
+
+- Do not create abstractions for hypothetical future requirements
+- Three similar-but-not-identical code blocks is not always a reason to abstract — wait for the pattern to stabilize
+- An abstraction that is harder to understand than the original code is a liability, not an asset
+- The right abstraction reveals intent. If the name cannot describe what it does in 3 words or fewer, reconsider.
+
+## Signals that an abstraction is wrong
+
+- The function needs many flags or mode switches to handle different callers
+- The caller has to know internal details to use it correctly
+- Tests for the abstraction are harder to read than tests for the original code
+- Removing the abstraction and inlining the logic would make the code clearer

package/template/.aioson/design-docs/file-size.md

@@ -0,0 +1,52 @@
+---
+description: "File size guidelines, alert thresholds, and split strategies"
+scope: "governance"
+agents: []
+---
+
+# File Size — Governance Rules
+
+> Loaded automatically by @dev and @deyvin. Override per-project via `.aioson/rules/`.
+
+## Thresholds
+
+| Lines | Status | Action |
+|-------|--------|--------|
+| < 300 | Ideal | Continue normally |
+| 300–500 | Acceptable | Monitor growth; do not split preemptively |
+| > 500 | Alert | Propose split before writing more code |
+
+Lines are counted as pure logic — comments, blank lines, and closing braces do not count toward the threshold.
+
+## Alert protocol
+
+When estimating that a resulting file will exceed 500 lines:
+
+1. Emit the alert with the estimated line count and file path
+2. List 2–3 concrete extraction alternatives with real file paths
+3. `@dev`: wait for user confirmation before proceeding
+4. `@deyvin` pair mode: present alternatives and continue after 1 turn with no response
+
+The alert is never blocking — it is a pause to think, not an impediment.
+
+## Common split strategies
+
+| Situation | Split approach |
+|-----------|---------------|
+| Large command / controller | Extract business logic to a `service/` or `lib/` module |
+| Validation logic growing | Extract to `validate-{domain}.js` / `{domain}_validator.py` |
+| Formatting / serialization | Extract to `format-{domain}.js` or a dedicated serializer |
+| Mixed read/write concerns | Separate into a reader and a writer module |
+| Route file growing | Group into feature sub-routers |
+| Large test file | Split by domain or by test type (unit / integration / e2e) |
+| Large React component | Extract sub-components and move logic to a custom hook |
+| Large class with many methods | Extract related method groups into collaborator classes |
+
+## Exceptions
+
+These file types are exempt from the size guideline:
+
+- Internationalization / locale files (`messages.json`, `en.yml`, `pt-BR.ts`)
+- Test fixtures and factories
+- Auto-generated files (migrations with timestamps, GraphQL schemas, OpenAPI specs)
+- Configuration files with many entries (`routes.php`, `config/app.ts`, `webpack.config.js`)