@jaimevalasek/aioson 1.7.2 → 1.9.0

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/context/project-pulse.md

@@ -1,34 +1,34 @@
----
-updated_at: null
-last_agent: null
-last_gate: null
-active_features: 0
-blocked: false
-blocked_reason: null
----
-
-# Project Pulse
-
-> Global project state. Updated by every agent at session end.
-> Read this FIRST when starting any session to orient quickly.
-> Max 30 lines of content — trim older entries when growing beyond that.
-
-## Active work
-
-| Feature | Phase | Agent | Status | Last checkpoint |
-|---------|-------|-------|--------|-----------------|
-| — | — | — | — | — |
-
-## Recent activity (last 3 sessions)
-
-| Date | Agent | Action | Result |
-|------|-------|--------|--------|
-| — | — | — | — |
-
-## Blockers
-
-None.
-
-## Next recommended action
-
-No active work. Start with `@product` for a new feature or `@setup` for a new project.
+---
+updated_at: null
+last_agent: null
+last_gate: null
+active_features: 0
+blocked: false
+blocked_reason: null
+---
+
+# Project Pulse
+
+> Global project state. Updated by every agent at session end.
+> Read this FIRST when starting any session to orient quickly.
+> Max 30 lines of content — trim older entries when growing beyond that.
+
+## Active work
+
+| Feature | Phase | Agent | Status | Last checkpoint |
+|---------|-------|-------|--------|-----------------|
+| — | — | — | — | — |
+
+## Recent activity (last 3 sessions)
+
+| Date | Agent | Action | Result |
+|------|-------|--------|--------|
+| — | — | — | — |
+
+## Blockers
+
+None.
+
+## Next recommended action
+
+No active work. Start with `@product` for a new feature or `@setup` for a new project.

package/template/.aioson/context/seeds/seed-example.md

@@ -1,27 +1,27 @@
----
-slug: example
-title: Exemplo de seed — substitua com sua ideia
-created: {ISO-date}
-trigger: ao iniciar milestone de {feature relacionada}
-scope_estimate: MICRO
-status: dormant
----
-
-## Ideia
-
-Descreva a ideia em 2-5 linhas. O que seria implementado e qual valor entregaria.
-
-## Codebase breadcrumbs
-
-Onde no código atual isso se encaixaria. O que existiria ou seria modificado.
-Ex: "src/billing/ ainda não existe — seria criada aqui"
-
-## Por que não agora
-
-Razão objetiva para não entrar no backlog agora.
-Ex: "Feature A precisa estar pronta antes", "não há demanda validada ainda"
-
-## Trigger condition
-
-Condição específica que deve fazer esta seed surfaçar.
-Ex: "quando iniciar milestone de pagamentos", "quando usuários pedirem 3+ vezes"
+---
+slug: example
+title: Exemplo de seed — substitua com sua ideia
+created: {ISO-date}
+trigger: ao iniciar milestone de {feature relacionada}
+scope_estimate: MICRO
+status: dormant
+---
+
+## Ideia
+
+Descreva a ideia em 2-5 linhas. O que seria implementado e qual valor entregaria.
+
+## Codebase breadcrumbs
+
+Onde no código atual isso se encaixaria. O que existiria ou seria modificado.
+Ex: "src/billing/ ainda não existe — seria criada aqui"
+
+## Por que não agora
+
+Razão objetiva para não entrar no backlog agora.
+Ex: "Feature A precisa estar pronta antes", "não há demanda validada ainda"
+
+## Trigger condition
+
+Condição específica que deve fazer esta seed surfaçar.
+Ex: "quando iniciar milestone de pagamentos", "quando usuários pedirem 3+ vezes"

package/template/.aioson/context/spec.md.template

@@ -1,54 +1,54 @@
----
-project: "<project_name>"
-updated: "<ISO-8601>"
----
-
-# Project Spec
-
-> Living document — update at the end of each working session via `*update-spec`.
-> Read at the start of each session before any prompt.
-
-## Stack
-[Copy from project.context.md § Stack]
-
-## Current state
-[What phase is the project in right now?
-Example: "Auth module complete. Starting appointments CRUD."]
-
-## Features
-
-### Done
-- (none yet)
-
-### In progress
-- (none yet)
-
-### Planned
-- [List features from prd.md if available, or high-level goals]
-
-## Open decisions
-- [Unresolved architectural or product questions]
-
-## Key decisions
-- [YYYY-MM-DD] [Decision made] — [Reason / trade-off accepted]
-
-## Session Learnings
-
-> Updated automatically at the end of each productive session.
-> Read at the start of each session to inform behavior.
-
-### Preferences
-- (none yet)
-
-### Process Patterns
-- (none yet)
-
-### Domain Insights
-- (none yet)
-
-### Quality Signals
-- (none yet)
-
-## Notes
-- [Important context, warnings, or constraints for future sessions]
-- [Known tech debt or deferred work]
+---
+project: "<project_name>"
+updated: "<ISO-8601>"
+---
+
+# Project Spec
+
+> Living document — update at the end of each working session via `*update-spec`.
+> Read at the start of each session before any prompt.
+
+## Stack
+[Copy from project.context.md § Stack]
+
+## Current state
+[What phase is the project in right now?
+Example: "Auth module complete. Starting appointments CRUD."]
+
+## Features
+
+### Done
+- (none yet)
+
+### In progress
+- (none yet)
+
+### Planned
+- [List features from prd.md if available, or high-level goals]
+
+## Open decisions
+- [Unresolved architectural or product questions]
+
+## Key decisions
+- [YYYY-MM-DD] [Decision made] — [Reason / trade-off accepted]
+
+## Session Learnings
+
+> Updated automatically at the end of each productive session.
+> Read at the start of each session to inform behavior.
+
+### Preferences
+- (none yet)
+
+### Process Patterns
+- (none yet)
+
+### Domain Insights
+- (none yet)
+
+### Quality Signals
+- (none yet)
+
+## Notes
+- [Important context, warnings, or constraints for future sessions]
+- [Known tech debt or deferred work]

package/template/.aioson/context/user-profile.md

@@ -1,42 +1,42 @@
----
-created: {ISO-date}
-last_updated: {ISO-date}
-questionnaire_completed: false
----
-
-# Developer Profile
-
-## Communication style
-<!-- direto | equilibrado | explicativo -->
-preference: equilibrado
-
-## Decision style
-<!-- opções-com-tradeoffs | recomendacao-unica | depende-do-contexto -->
-preference: depende-do-contexto
-
-## Tech philosophy
-<!-- explícito | convencional | pragmatico -->
-preference: pragmatico
-
-## Autonomy preference
-<!-- aprovacao-por-step | aprovacao-em-gates | execucao-autonoma -->
-preference: aprovacao-em-gates
-
-## Feedback style
-<!-- critica-direta | colaborativo | neutro -->
-preference: neutro
-
-## Scope tolerance
-<!-- strict | sugestoes-ok | flexible -->
-preference: sugestoes-ok
-
-## Detail level
-<!-- so-resultado | contexto-quando-relevante | sempre-explicar -->
-preference: contexto-quando-relevante
-
-## Risk tolerance
-<!-- conservador | equilibrado | arrojado -->
-preference: equilibrado
-
-## Notes
-<!-- observações específicas do usuário sobre preferências -->
+---
+created: {ISO-date}
+last_updated: {ISO-date}
+questionnaire_completed: false
+---
+
+# Developer Profile
+
+## Communication style
+<!-- direto | equilibrado | explicativo -->
+preference: equilibrado
+
+## Decision style
+<!-- opções-com-tradeoffs | recomendacao-unica | depende-do-contexto -->
+preference: depende-do-contexto
+
+## Tech philosophy
+<!-- explícito | convencional | pragmatico -->
+preference: pragmatico
+
+## Autonomy preference
+<!-- aprovacao-por-step | aprovacao-em-gates | execucao-autonoma -->
+preference: aprovacao-em-gates
+
+## Feedback style
+<!-- critica-direta | colaborativo | neutro -->
+preference: neutro
+
+## Scope tolerance
+<!-- strict | sugestoes-ok | flexible -->
+preference: sugestoes-ok
+
+## Detail level
+<!-- so-resultado | contexto-quando-relevante | sempre-explicar -->
+preference: contexto-quando-relevante
+
+## Risk tolerance
+<!-- conservador | equilibrado | arrojado -->
+preference: equilibrado
+
+## Notes
+<!-- observações específicas do usuário sobre preferências -->

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