From ec1e86ea830c07dbf4afdd1ae10dc5c945c0e00f Mon Sep 17 00:00:00 2001 From: Claude Date: Tue, 2 Jun 2026 13:31:14 +0000 Subject: [PATCH] docs(scaffold): fill the repo's own AGENTS.md, CLAUDE.md, copilot, .specs/product Closes #99. This repo is the canonical scaffold whose whole purpose is to remove placeholders from host projects, yet its own AGENTS.md and CLAUDE.md still carried `` lines and the host-only placeholder list (``, ``, ``, ``, ``, ``), and the commands block still pointed at generic `npm run dev` / `npm run build` that do not exist here. The `.specs/product/` files were also template prose. Fill them with the repo's real identity: - AGENTS.md, CLAUDE.md, and .github/copilot-instructions.md now declare the real stack (Python 3.10+ canonical with `orjson` + `diskcache`, Node CLI mirror at `bin/cli.js`, optional Rust/PyO3 acceleration, Playwright E2E), list the actual project-identity slots (CLI tool, no UI, PyPI-only since 0.7.x), and document the commands that actually run here (`python -m unittest discover`, `ruff check`, `node scripts/check-version-sync.js`, `(cd rust && maturin develop)`). - `.specs/product/VISION.md` describes the real product thesis: deterministic project context as a compilable artifact, not a prompt. - `.specs/product/DOMAIN.md` lists the real entities (ProjectFile, Precedent, Module/Layer, Symbol, CallEdge, Endpoint, Screen, IndexState, Receipt), the seven critical rules (schema is contract, determinism, idempotency, no-LLM-on-the-critical-path, generic normalization, lightweight deps, cross-runtime parity) and the documented edge cases. - `.specs/product/PERSONAS.md` captures the five real consumers (P1 SendSprint orchestrator, P2 simplicio-dev-cli, P3 human maintainer, P4 CI / DoD, P5 release maintainer) with the commands each calls and the guarantees they need. No code changes. CLAUDE.md and .github/copilot-instructions.md stay aligned with AGENTS.md as the repo's own contributing rule requires. https://claude.ai/code/session_01JdmemqddwFnvbceWyuDE8m --- .github/copilot-instructions.md | 40 ++++--- .specs/product/DOMAIN.md | 186 +++++++++++++------------------ .specs/product/PERSONAS.md | 188 ++++++++++++-------------------- .specs/product/VISION.md | 96 ++++++++-------- AGENTS.md | 74 +++++++------ CLAUDE.md | 68 +++++++----- 6 files changed, 295 insertions(+), 357 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 0012bcc..cc252d6 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -12,16 +12,17 @@ ## Stack -`` (placeholder — substitui pela stack real do projeto, ex: `Node.js 20 + TypeScript + Next.js 14 + Playwright + Vitest`). - -- Linguagem principal: `` -- Framework web/API: `` -- Banco de dados: `` -- Test runner unit: `` (Vitest, Jest, pytest, xUnit) -- Test runner E2E: **Playwright** (config em `playwright.config.ts`) -- Linter/formatter: `` (ESLint + Prettier, Ruff, dotnet format) -- CI/CD: GitHub Actions (`.github/workflows/`) -- Deploy: `` (ver `.specs/workflow/RELEASE.md`) +**Python 3.10+ (`orjson`, `diskcache`) + Node.js CLI + optional Rust/PyO3 crate + Playwright E2E.** + +- Linguagem principal: **Python 3.10+** (PyPI `simplicio-mapper`); espelho Node 18+ em `bin/cli.js` + `bin/mapper-artifacts.js` mantido em paridade. +- Framework web/API: n/a — projeto é CLI/library. +- Banco de dados: n/a — cache opcional em disco via `diskcache` em `.simplicio/cache/`. +- Test runner unit: **`python -m unittest discover -s tests/python`** (também via `pytest tests/python -q`) e **`node --test tests/unit`**. +- Test runner E2E: **Playwright** (config em `playwright.config.ts`). +- Linter/formatter: **`ruff`** (ver `[tool.ruff]` em `pyproject.toml`) e `node scripts/lint.js` (shell + JS). +- CI/CD: GitHub Actions (`.github/workflows/`). DoD em `dod.yml`. Publish em `publish-pypi.yml` (PyPI-only desde 0.7.x). +- Distribuição: PyPI canonical; npm `@wesleysimplicio/llm-project-mapper` mantido só para versões antigas, sem releases novos. +- Opt-in: crate Rust em `rust/` via `maturin develop --release` (ADR-002). > Antes de adicionar dependência nova: pergunta ao humano. Sem exceção. @@ -30,29 +31,34 @@ ## Comandos importantes ```bash -# desenvolvimento -npm run dev -npm run build +# desenvolvimento / smoke local +node bin/cli.js --help +python -m simplicio_mapper.cli --help +python -m build # qualidade npm run lint -npm run lint:fix +ruff check simplicio_mapper tests/python +node scripts/check-version-sync.js +python -m unittest discover -s tests/python +node --test tests/unit npm test -npm test -- --coverage # E2E npx playwright install npx playwright test npx playwright show-report +# Rust opt-in +(cd rust && maturin develop --release) +python -m pytest tests/python/test_native.py + # git/PR git checkout -b feat/- gh pr create --fill gh run watch ``` -Adapta pra `pnpm`, `yarn`, `bun`, `dotnet`, `python`, `go` conforme stack real. - --- ## Padrão de sincronização deste projeto diff --git a/.specs/product/DOMAIN.md b/.specs/product/DOMAIN.md index 2037698..12bc41a 100644 --- a/.specs/product/DOMAIN.md +++ b/.specs/product/DOMAIN.md @@ -1,127 +1,89 @@ -# DOMAIN — +# DOMAIN — simplicio-mapper -Glossário e modelo de entidades do . Quando um termo aparecer no código (variável, classe, endpoint), ele deve estar aqui antes. Quando alguém perguntar "o que é X?", a resposta vem deste arquivo. - -> Regra: nada de sinônimos não documentados. Se "usuário" e "cliente" significam a mesma coisa, escolha um e mantenha em todo o repo. +Vocabulário canônico do produto. Antes de criar nome novo, procura aqui; +antes de mudar nome existente, atualiza tudo que referencia. --- -## Glossário - -Tabela ordenada alfabeticamente. Manter conciso (1-2 linhas por termo). - -| Termo | Definição | Onde aparece | -|---|---|---| -| `` | | DB, API, UI | -| `` | | DB, API | -| `` | | Regra de negócio | -| `` | Estado pelo qual `` passa: `pending` -> `active` -> `archived`. | DB, UI | -| `` | Algo que aconteceu (passado), imutável. Ex: `OrderPlaced`. | Event log | -| `` | Pedido para algo acontecer (futuro). Ex: `PlaceOrder`. | API | +## Entidades + +- **Project** — diretório raiz que o mapper analisa. Identificado por `cwd` + e (quando disponível) por commit SHA de `git rev-parse HEAD`. +- **ProjectFile** — entry deterministica do `files[]` em `project-map.json`. + Carrega `path`, `language`, `roles`, `imports`, `exports`, `importance`, + `file_hash`, `git_status`, `size_bytes`, `last_modified`. +- **Precedent** — snippet de alta qualidade extraído pelo mapper, tagueado + por `change_type` (`feature`, `bugfix`, `test`, `refactor`, `docs`...). +- **ArchitectureSignal** — flag de framework/biblioteca detectado por + heurística (e.g. `nextjs`, `fastapi`, `dotnet`, `prisma`). +- **Module / Layer** — agrupamento heurístico em `architecture-inventory.json` + com camadas `entrypoint`, `domain`, `route`, `ui`, `config`, `test`. +- **Symbol** — classe, função, método ou export detectado, com `defined_in`, + `line` e `evidence`. +- **CallEdge** — relação `imports` ou `calls` em `call-graph.json` com + `confidence` (1.0 para imports resolvidos, <1.0 para heurísticas). +- **Endpoint** (`endpoints` command) — par método+path normalizado vindo de + cliente (`client_calls`) ou servidor (`server_routes`), comparado por + `missing_from_server`. +- **Screen** (`screens` command) — rota Angular declarativa com persona, + redirect, guard e parâmetros dinâmicos. +- **IndexState** — `simplicio.mapper-index-state/v1`, fingerprint persistido + em `.simplicio/index-state.json` que guarda o último HEAD/status para o + curto-circuito do `index`. +- **Receipt** — registro de execução em `.receipts/`, padrão YOOL_TUPLE_HAMT + §1.8.4 (com `tuple_id`, `yool_id`, `cost.tokens`, `cost.usd`). --- -## Entidades principais - -Lista das principais entidades de negócio. Cada uma com 1-3 frases de descrição. - -### `` - -- O que é: -- Atributos chave: -- Ciclo de vida: transições -> término> -- Quem cria: -- Quem consome: - -### `` - -- O que é: -- Atributos chave: <...> -- Relação com ``: <1:N, 1:1, N:N e por quê> - -### `` - -- O que é: -- Atributos chave: <...> -- Regras de negócio: +## Regras críticas + +1. **Schema é contrato.** Mudar shape de `simplicio.project-map/v1`, + `simplicio.precedent-index/v1`, `simplicio.architecture-inventory/v1`, + `simplicio.symbol-index/v1`, `simplicio.call-graph/v1`, + `simplicio.endpoint-inventory/v1` ou `simplicio.screen-inventory/v1` + exige ADR e bump de schema. +2. **Determinismo.** Mesmo input → mesmo output. Ordenação estável, + timestamps em UTC, sem inclusão de paths absolutos do host. +3. **Idempotência.** `simplicio-mapper index ` deve retornar exit 2 + em <200 ms quando o fingerprint não mudou. Foreground e background não + podem rodar concorrentes; lock em `.simplicio/index.lock`. +4. **Sem LLM no caminho crítico.** O mapper não chama modelo para gerar + artefato. Heurísticas e parsers só. +5. **Generalização sobre nomes.** Endpoint path normalization usa só + placeholders, UUIDs e segments numéricos. Slugs específicos de host + ficam intactos. +6. **Dependências leves.** `orjson` e `diskcache` são as únicas runtime + deps obrigatórias do pacote Python. A crate Rust é opt-in e o pacote + funciona sem ela. +7. **Cross-runtime parity.** A CLI Python (canonical) e a CLI Node em + `bin/cli.js` devem emitir os mesmos artefatos para a mesma entrada; + divergência é bug. --- -## Diagrama de entidades - -Visão simplificada das relações. Atualizar quando uma entidade nova for criada ou um relacionamento mudar. - -```mermaid -erDiagram - USER ||--o{ ENTIDADE1 : "creates" - ENTIDADE1 ||--o{ ENTIDADE2 : "contains" - ENTIDADE1 }o--|| ENTIDADE3 : "belongs to" - - USER { - uuid id - string email - string name - } - ENTIDADE1 { - uuid id - uuid user_id - string status - datetime created_at - } - ENTIDADE2 { - uuid id - uuid entidade1_id - string title - } - ENTIDADE3 { - uuid id - string name - } -``` +## Casos de borda + +- **Repo sem git** — `_compute_fingerprint` cai no fallback de mtimes. +- **Repo grande (>10k arquivos)** — `--background` evita bloquear o caller; + o foreground reusa o último JSON estável até o background terminar. +- **Repo com tooling múltiplo** (.NET + Angular + Python) — `.angular`, + `obj`, `bin/Debug/`, `output/`, `__pycache__`, `.pytest_cache`, + `.ruff_cache`, `.gradle`, `target` são pulados; `bin/` puro (Node CLI) é + preservado. +- **Repo com edits unstaged** — `git status --porcelain --untracked-files=all` + marca como `M`/`??`; mtime fallback usa `mtime_ns` + `size`. +- **Repo overlay (starter dropado sobre host)** — `.specs/`, `.claude/`, + `.codex/`, `.github/` podem estar gitignored no host sem afetar o + `project_mode`. --- -## Regras de negócio (invariantes) - -Coisas que nunca podem ser violadas. Cada uma deve virar teste. - -- INV-1: `` só passa de `pending` para `active` se ``. -- INV-2: Um `User` não pode ter mais de uma `` ativa. -- INV-3: `` é imutável; nunca edita, sempre acrescenta. -- INV-4: - ---- - -## Estados / máquinas de estado - -Quando uma entidade tem ciclo de vida não trivial, desenhar. - -```mermaid -stateDiagram-v2 - [*] --> Pending - Pending --> Active: approve() - Pending --> Rejected: reject() - Active --> Archived: archive() - Archived --> [*] - Rejected --> [*] -``` - ---- - -## Termos do que NÃO usamos - -Sinônimos vetados. Mantém vocabulário consistente. - -| Termo vetado | Usar em vez | -|---|---| -| `customer` | `user` | -| `record` | nome da entidade específica | -| `data` | `` | - ---- +## Fronteiras -## Histórico +`simplicio-mapper` **não**: -| Data | Mudança | Quem | -|---|---|---| -| YYYY-MM-DD | Criação inicial | | +- Roda LLM nem gera prompt. +- Aplica edits no código do host. +- Publica artefatos remotos (`export-docs` apenas copia local). +- Orquestra agentes (responsabilidade de `simplicio-sprint`). +- Trata billing/pricing (responsabilidade de `simplicio-prompt`). diff --git a/.specs/product/PERSONAS.md b/.specs/product/PERSONAS.md index 352fd06..a3899d0 100644 --- a/.specs/product/PERSONAS.md +++ b/.specs/product/PERSONAS.md @@ -1,139 +1,93 @@ -# PERSONAS — +# PERSONAS — simplicio-mapper -Quem usa . Cada persona é um arquétipo: representa um grupo real de pessoas com objetivos, frustrações e contexto comuns. Decisões de produto e features se justificam contra estas personas, não contra opiniões. - -> Regra: se uma feature não move a agulha de pelo menos uma persona aqui, ela não entra no backlog. +Quem consome o mapper, em que contexto, e qual é a expectativa concreta +de cada um. Use isso para decidir prioridades e quebrar empates de design. --- -## Persona 1 — `` - -**Arquétipo:** - -### Quem é - -- **Papel/profissão:** -- **Idade aproximada:** -- **Contexto profissional:** -- **Familiaridade com tech:** -- **Familiaridade com o :** - -### Objetivos - -O que essa persona quer alcançar? Listar 3-5. - -- Lançar releases pequenas e frequentes sem quebrar produção. -- Manter contexto do projeto consistente entre dias/semanas. -- Reduzir tempo gasto em setup repetitivo entre projetos. -- Trabalhar com IA sem virar refém de um único provedor. - -### Frustrações / dores +## P1 · Agent orchestrator (SendSprint / simplicio-sprint) -O que dói hoje? Cada item deve poder virar feature. - -- Specs ficam desatualizadas e o agente perde contexto na semana seguinte. -- Cada projeto novo começa do zero com instruction files inconsistentes. -- Tasks vagas viram retrabalho e PRs gigantes. -- Falta de gate automático faz código ruim chegar em produção. - -### Contexto de uso - -Onde, quando, como usa . - -- **Ambiente:** terminal + editor (VS Code/Cursor) + GitHub. -- **Frequência:** diariamente. -- **Sessão típica:** 2-6h focado, com pausas curtas. -- **Trigger principal:** começar projeto novo ou adicionar feature em projeto existente. - -### Métrica que importa para essa persona - -Como sabemos que estamos servindo bem? - -- -- +- **Quem** — bot que recebe uma sprint/issue e dispara agentes em lote. +- **Comando que chama** — `simplicio-mapper index ` antes de cada + execução de agente. +- **Quer** + - Exit codes estáveis (0/1/2), JSON estável (`--json`), idempotência + real (<200 ms quando nada mudou). + - Mensagens de erro acionáveis (`status="failed"`, `error="..."`). + - Lock que evita corridas com refreshes em background concorrentes. +- **Não tolera** — output não estruturado, schema drift, log ruidoso em + no-op. --- -## Persona 2 — `` - -**Arquétipo:** - -### Quem é - -- **Papel/profissão:** -- **Idade aproximada:** -- **Contexto profissional:** -- **Familiaridade com tech:** -- **Familiaridade com o :** - -### Objetivos - -- Padronizar como o time usa AI agents para reduzir variância de output. -- Garantir que onboarding de devs novos seja em horas, não semanas. -- Ter visibilidade do que está sendo construído sem ler todo PR. -- Manter qualidade alta mesmo com aumento de velocidade. - -### Frustrações / dores - -- Cada dev usa IA do seu jeito, gerando código inconsistente. -- Specs vivem em ferramentas diferentes (Notion, Linear, comentários de PR), nunca no repo. -- Code review vira gargalo porque PRs são grandes e mal explicados. -- Decisões arquiteturais passadas se perdem na rotação de pessoas. - -### Contexto de uso - -- **Ambiente:** GitHub + ferramentas de gestão (Linear/Jira) + reuniões. -- **Frequência:** revê o repo toda semana, não codifica todo dia. -- **Sessão típica:** 30-60 min de revisão. -- **Trigger principal:** abrir o repo para revisar PR, escrever ADR ou planejar sprint. - -### Métrica que importa - -- -- +## P2 · LLM-driven dev CLI (simplicio-dev-cli) + +- **Quem** — Python CLI 6-layer prompt (mapper + precedent + skill-router + + core + test + verify + retry) que entrega tasks com modelos médios e + fracos a >96 % de sucesso. +- **Comando que chama** — lê `.simplicio/project-map.json`, + `precedent-index.json`, `architecture-inventory.json`, `symbol-index.json`, + `call-graph.json` direto. +- **Quer** + - Sinal alto por token: `roles`, `importance`, `entry_points`, + `recent_changes`, `architecture.signals`. + - Precedents pré-tagueados por `change_type` para retrieval orientado + pela task. + - Schema previsível para o `_mapper` plug-point em `prompt.py`. +- **Não tolera** — paths absolutos do host, hashes voláteis, schema + divergente entre runtimes Node e Python. --- -## Persona 3 — `` (opcional) - -**Arquétipo:** - -### Quem é +## P3 · Engenheiro humano (manutenção/debug) -- Não é humano. É o agente (Claude Code, Codex, Copilot) lendo `AGENTS.md` e specs. -- "Idade", "contexto profissional" não se aplicam, mas tem capacidades e limitações reais. -- **Limitações:** janela de contexto, sem memória entre sessões, depende 100% do que está escrito no repo. +- **Quem** — pessoa que abre o repo, dá `simplicio-mapper docs .` e quer + entender módulos, layers, símbolos e relações sem ler todo o código. +- **Comando que chama** — `simplicio-mapper docs --json`, + `simplicio-mapper export-docs --target ./wiki-export`. +- **Quer** + - Markdown derivado dos JSONs em `.simplicio/docs/*.md` com layers, + call-graph, módulos. + - Diff legível semana a semana. +- **Não tolera** — docs alucinados, prosa LLM, conteúdo que não bate com + o código. -### Objetivos - -- Encontrar contexto rápido (VISION -> DESIGN -> task). -- Não inventar quando a spec não cobre. -- Validar trabalho contra DoD antes de fechar PR. -- Reaproveitar skills existentes em vez de reescrever lógica. - -### Frustrações / dores +--- -- Specs ambíguas geram código errado. -- Falta de exemplos concretos faz desviar do padrão. -- Hooks/CI sem mensagens claras dificultam autocorreção. -- Tasks sem critério de aceite testável geram retrabalho. +## P4 · CI / DoD gate (.github/workflows) -### Contexto de uso +- **Quem** — workflows `dod.yml`, `python-ci.yml`, `scaffold-self-check.yml`, + `publish-pypi.yml`. +- **Comando que chama** — não chama o mapper diretamente, mas depende do + pacote Python ser instalável, dos testes (`unittest`/`pytest`) verdes e + do lint (`ruff`) limpo. +- **Quer** + - Build reproduzível (`hatchling>=1.27,<1.28`). + - Versões alinhadas (`scripts/check-version-sync.js`). + - Pytest verde antes de qualquer publish. +- **Não tolera** — divergência de versão entre `package.json`, + `pyproject.toml`, `__init__.py`. -- **Ambiente:** dentro do repo via CLI/IDE. -- **Frequência:** sempre que invocado. -- **Sessão típica:** uma task por vez, idealmente pequena. -- **Trigger principal:** humano dispara comando ou abre task. +--- -### Métrica que importa +## P5 · Maintainer de pacote (release/PyPI) -- -- +- **Quem** — humano que faz o bump, escreve o changelog e dispara o + publish. +- **Comando que chama** — `npm test`, `python -m pytest tests/python`, + `python -m build`, `python -m twine check dist/*`, `git tag`. +- **Quer** + - Changelog Keep-a-Changelog 1.1.0 atualizado. + - Workflow `publish-pypi.yml` idempotente (skip se versão igual à + publicada). + - Wheels e sdist passando em `twine check`. +- **Não tolera** — release publicado sem changelog ou com testes + vermelhos, secret de token vazando em commit/log. --- -## Histórico +## Não-personas -| Data | Mudança | Quem | -|---|---|---| -| YYYY-MM-DD | Criação inicial | | +- **Não atendemos** agentes que pedem o mapper para gerar prosa ou opinar + sobre código. Isso é deliberado: o mapper só extrai sinais + observáveis. Quem opina é o consumidor. diff --git a/.specs/product/VISION.md b/.specs/product/VISION.md index c538ab6..24c9678 100644 --- a/.specs/product/VISION.md +++ b/.specs/product/VISION.md @@ -1,81 +1,77 @@ -# VISION — +# VISION — simplicio-mapper -Documento de uma página. Mantém o time alinhado sobre o porquê. Atualizar quando a tese mudar; nunca apagar a versão anterior sem registrar em ADR. +Documento de uma página. Mantém o time alinhado sobre o porquê. Atualizar +quando a tese mudar; registrar versão anterior em ADR antes de reescrever. --- ## Problema -Descreva em 2-3 frases o problema concreto que o produto resolve. +Agentes de coding (Claude Code, Codex, Copilot, Cursor, Aider, Hermes) abrem +qualquer repo sem contexto e gastam tokens redescobrindo a arquitetura, o +naming, os entry points e os precedents toda execução. Em projetos médios e +grandes, isso vira: -- Quem sente dor hoje no ? -- Qual o custo dessa dor (tempo, dinheiro, frustração, oportunidade perdida)? -- Por que as soluções existentes não resolvem? +- variância alta entre runs (mesma task, resultados diferentes); +- prompts grandes e caros sem sinal claro; +- bugs por suposição (paths que não existem, dependências erradas, schemas + divergentes do que o repo realmente expõe). -> Exemplo: "Times que constroem produtos com IA perdem tempo demais configurando contexto, instruction files e specs do zero a cada projeto. Isso atrasa a primeira release em semanas e produz repos inconsistentes." +As soluções existentes ou são generalistas (RAG genérico em todo arquivo, +caro e ruidoso) ou específicas demais para um único framework. --- ## Quem usa -Resumo das personas. Detalhes completos em `PERSONAS.md`. - -- **Persona primária:** -- **Persona secundária:** -- **Quem NÃO é o público:** - -Veja `./PERSONAS.md` para objetivos, frustrações e contexto de uso de cada persona. +- **Agentes** rodando em CLIs, web app, IDE plugins, ou em sessões de + orquestração (SendSprint, simplicio-dev-cli, simplicio-sprint, Hyperframes). +- **Humanos** que mantêm esses agentes — engenheiros que precisam que a + primeira ação do agente no repo seja consistente, idempotente e barata. --- -## Diferencial - -O que faz diferente das alternativas? Listar 3-5 pontos verificáveis. - -- Diferencial 1: -- Diferencial 2: -- Diferencial 3: -- Diferencial 4: - -Evitar buzzwords vazios ("o melhor", "revolucionário"). Cada bullet deve poder virar teste. +## Proposta de valor ---- - -## Métricas de sucesso +`simplicio-mapper` produz artefatos JSON estáveis e versionados sobre **um +repo qualquer**, em segundos, sem pedir LLM no caminho crítico: -Indicadores que dizem se a tese está certa. Mensuráveis. Com baseline e meta. +- `.simplicio/project-map.json` — inventário determinístico de arquivos, + linguagens, roles, imports/exports e importance score. +- `.simplicio/precedent-index.json` — exemplos de alta qualidade (snippets) + para retrieval orientado por mudança. +- `.simplicio/architecture-inventory.json`, `symbol-index.json`, + `call-graph.json` — visão de módulos, símbolos e relações. +- Bootstrap idempotente via `simplicio-mapper index ` que curto-circuita + em <200 ms quando o repo não mudou (exit codes 0/1/2 estáveis para + orquestradores). -| Métrica | Baseline | Meta (3 meses) | Como medimos | -|---|---|---|---| -| Tempo até primeira release | | | Data primeiro commit -> data deploy v0.1 | -| Cobertura de testes mínima por PR | | | CI gate | -| Cycle time médio de task | | | Issue closed - issue created | -| Reverts em produção / mês | | | git log no main | +Tudo opera offline, com dependências leves (`orjson`, `diskcache`) e um +fast-path opt-in em Rust via PyO3 para hashing/parsing em escala. --- -## Não-objetivos - -O que intencionalmente NÃO faz. Tão importante quanto o que faz, evita scope creep. +## Tese central -- Não somos . Quem precisa de deve usar . -- Não otimizamos para . Optamos por em troca. -- Não entregamos porque . - -> Exemplo: "Não somos um framework. Não geramos código. Entregamos estrutura e processo." +Contexto de projeto deve ser um **artefato compilável**, não um prompt cada +hora. Quem dá esse contexto para os agentes é uma camada determinística +versionada (schemas `simplicio.*/v1`), não o modelo. O modelo só decide. --- -## Tese de longo prazo - -Em 12 meses, se der certo, como o mundo do está diferente? +## Out of scope -> Frase única. Memorável. Algo que qualquer pessoa do consegue repetir sem ler. +- Geração ou edição de código a partir dos artefatos. +- Orquestração multi-agente (responsabilidade de `simplicio-sprint`). +- LLM gateways, billing, pricing (responsabilidade de `simplicio-prompt`). --- -## Histórico +## Sucesso -| Data | Versão | Mudança | Quem | -|---|---|---|---| -| YYYY-MM-DD | 0.1 | Criação inicial | | +- Agentes integrados com `simplicio-mapper` reduzem variância e tokens em + tarefas reais (medido pelos consumidores: simplicio-dev-cli benchmarks, + SendSprint progress tables). +- `simplicio-mapper index .` roda em <200 ms quando idempotente, e o JSON + contract permanece compatível com agentes que já consomem `v1`. +- Toda mudança de schema vem com ADR e bump de versão. diff --git a/AGENTS.md b/AGENTS.md index 34e8803..fc22f60 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -18,14 +18,18 @@ Before changing code, agents should check the project-specific operational docs: | Common failures and fixes | `docs/troubleshooting.md` | | Reusable local commands | `scripts/README.md` | -Key placeholders to replace in real projects: +Project identity (this repo is the canonical scaffold itself, so no host +placeholders — fill these row-by-row when copying the file into a host +project): -- `` -- `` -- `` -- `` -- `` -- `` +| Slot | Value here | +|---|---| +| App name | `simplicio-mapper` (npm `@wesleysimplicio/llm-project-mapper`) | +| Frontend URL | n/a — CLI tool, no UI runtime | +| Backend URL | n/a — local mapper, no service endpoint | +| Database | n/a — file-system only, optional `diskcache` on disk | +| Auth flow | n/a — no user auth; PyPI/npm tokens via repo secrets only | +| Evidence command | `npx playwright test --reporter=list,html` (writes to `playwright-report/` + `test-results/`) | Agent checklist: @@ -61,18 +65,19 @@ Antes de qualquer análise, o agent **DEVE** ler `.starter-meta.json` e respeita ## Stack -`` (placeholder — substitui pela stack real do projeto, ex: `Node.js 20 + TypeScript + Next.js 14 + Playwright + Vitest`). +**Python 3.10+ (`orjson`, `diskcache`) + Node.js CLI + optional Rust/PyO3 acceleration crate + Playwright E2E.** -Detalhes completos: +Detalhes: -- Linguagem principal: `` -- Framework web/API: `` -- Banco de dados: `` -- Test runner unit: `` (sugestão: Vitest, Jest, pytest, xUnit) -- Test runner E2E: **Playwright** (config em `playwright.config.ts`) -- Linter/formatter: `` (sugestão: ESLint + Prettier, Ruff, dotnet format) -- CI/CD: GitHub Actions (ver `.github/workflows/`) -- Deploy: `` (Vercel/Netlify/Docker/Azure/AWS — ver `.specs/workflow/RELEASE.md`) +- Linguagem principal: **Python 3.10+** (canonical PyPI package `simplicio-mapper`); um espelho Node 18+ vive em `bin/cli.js` + `bin/mapper-artifacts.js` mantido em paridade. +- Framework web/API: n/a — projeto é um CLI/library. +- Banco de dados: n/a — cache opcional em disco via `diskcache` (`.simplicio/cache/`). +- Test runner unit: **`python -m unittest discover -s tests/python`** (também roda via `pytest tests/python -q`) e **`node --test tests/unit`**. +- Test runner E2E: **Playwright** (config em `playwright.config.ts`). +- Linter/formatter: **`ruff`** (Python, ver `[tool.ruff]` em `pyproject.toml`) e `node scripts/lint.js` (shell + JS). +- CI/CD: GitHub Actions (ver `.github/workflows/`). DoD gate em `dod.yml`. Publish em `publish-pypi.yml` (PyPI-only desde 0.7.x). +- Distribuição: **PyPI** `simplicio-mapper` é o canal oficial; versões anteriores do pacote npm `@wesleysimplicio/llm-project-mapper` permanecem no registry mas não recebem novos releases. +- Opt-in: crate Rust em `rust/` build via `maturin develop --release` (ADR-002). > Antes de adicionar dependência nova: **pergunta ao usuário**. Sem exceção. @@ -81,30 +86,35 @@ Detalhes completos: ## Comandos importantes ```bash -# desenvolvimento -npm run dev # sobe app local -npm run build # build de produção +# desenvolvimento / smoke local +node bin/cli.js --help # CLI Node +python -m simplicio_mapper.cli --help # CLI Python (canonical) +python -m build # gera dist/*.whl + .tar.gz # qualidade -npm run lint # lint + format check -npm run lint:fix # lint + format auto-fix -npm test # unit tests -npm test -- --coverage # unit + coverage report (gate >= 80%) +npm run lint # JS + shell lint (scripts/lint.js) +ruff check simplicio_mapper tests/python # Python lint +node scripts/check-version-sync.js # versões alinhadas (package/pyproject/__init__) +python -m unittest discover -s tests/python # Python unit +node --test tests/unit # Node unit +npm test # cross alias (chama node --test) # E2E -npx playwright install # instala browsers (1ª vez) -npx playwright test # roda suite E2E -npx playwright test --ui # modo interativo -npx playwright show-report # abre relatório último run +npx playwright install # instala browsers (1ª vez) +npx playwright test # roda suite E2E +npx playwright test --ui # modo interativo +npx playwright show-report # abre relatório último run + +# Rust opt-in +(cd rust && maturin develop --release) # builda extensão nativa no venv +python -m pytest tests/python/test_native.py # cobre o caminho nativo # git/PR git checkout -b feat/- -gh pr create --fill # usa template de PR -gh run watch # acompanha CI do branch atual +gh pr create --fill # usa template de PR +gh run watch # acompanha CI do branch atual ``` -Adapta os comandos pra stack real (`pnpm`, `yarn`, `bun`, `dotnet`, `python`, `go`). - ## Shell token-smart (RTK CLI, opcional) Se `rtk` estiver instalado na máquina, prefira-o em tarefas shell-heavy e de exploração para reduzir ruído e consumo de tokens: diff --git a/CLAUDE.md b/CLAUDE.md index d130e10..f155df7 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -26,12 +26,14 @@ Before changing code, agents should check the project-specific operational docs: Key placeholders to replace in real projects: -- `` -- `` -- `` -- `` -- `` -- `` +| Slot | Value here | +|---|---| +| App name | `simplicio-mapper` (npm `@wesleysimplicio/llm-project-mapper`) | +| Frontend URL | n/a — CLI tool, no UI runtime | +| Backend URL | n/a — local mapper, no service endpoint | +| Database | n/a — file-system only, optional `diskcache` on disk | +| Auth flow | n/a — no user auth; PyPI/npm tokens via repo secrets only | +| Evidence command | `npx playwright test --reporter=list,html` (writes to `playwright-report/` + `test-results/`) | Agent checklist: @@ -67,18 +69,19 @@ Antes de qualquer análise, o agent **DEVE** ler `.starter-meta.json` e respeita ## Stack -`` (placeholder — substitui pela stack real do projeto, ex: `Node.js 20 + TypeScript + Next.js 14 + Playwright + Vitest`). +**Python 3.10+ (`orjson`, `diskcache`) + Node.js CLI + optional Rust/PyO3 acceleration crate + Playwright E2E.** -Detalhes completos: +Detalhes: -- Linguagem principal: `` -- Framework web/API: `` -- Banco de dados: `` -- Test runner unit: `` (sugestão: Vitest, Jest, pytest, xUnit) -- Test runner E2E: **Playwright** (config em `playwright.config.ts`) -- Linter/formatter: `` (sugestão: ESLint + Prettier, Ruff, dotnet format) -- CI/CD: GitHub Actions (ver `.github/workflows/`) -- Deploy: `` (Vercel/Netlify/Docker/Azure/AWS — ver `.specs/workflow/RELEASE.md`) +- Linguagem principal: **Python 3.10+** (canonical PyPI package `simplicio-mapper`); um espelho Node 18+ vive em `bin/cli.js` + `bin/mapper-artifacts.js` mantido em paridade. +- Framework web/API: n/a — projeto é um CLI/library. +- Banco de dados: n/a — cache opcional em disco via `diskcache` (`.simplicio/cache/`). +- Test runner unit: **`python -m unittest discover -s tests/python`** (também roda via `pytest tests/python -q`) e **`node --test tests/unit`**. +- Test runner E2E: **Playwright** (config em `playwright.config.ts`). +- Linter/formatter: **`ruff`** (Python, ver `[tool.ruff]` em `pyproject.toml`) e `node scripts/lint.js` (shell + JS). +- CI/CD: GitHub Actions (ver `.github/workflows/`). DoD gate em `dod.yml`. Publish em `publish-pypi.yml` (PyPI-only desde 0.7.x). +- Distribuição: **PyPI** `simplicio-mapper` é o canal oficial; versões anteriores do pacote npm `@wesleysimplicio/llm-project-mapper` permanecem no registry mas não recebem novos releases. +- Opt-in: crate Rust em `rust/` build via `maturin develop --release` (ADR-002). > Antes de adicionar dependência nova: **pergunta ao usuário**. Sem exceção. @@ -87,26 +90,33 @@ Detalhes completos: ## Comandos importantes ```bash -# desenvolvimento -npm run dev # sobe app local -npm run build # build de producao +# desenvolvimento / smoke local +node bin/cli.js --help # CLI Node +python -m simplicio_mapper.cli --help # CLI Python (canonical) +python -m build # gera dist/*.whl + .tar.gz # qualidade -npm run lint # lint + format check -npm run lint:fix # lint + format auto-fix -npm test # unit tests -npm test -- --coverage # unit + coverage report (gate >= 80%) +npm run lint # JS + shell lint (scripts/lint.js) +ruff check simplicio_mapper tests/python # Python lint +node scripts/check-version-sync.js # versões alinhadas (package/pyproject/__init__) +python -m unittest discover -s tests/python # Python unit +node --test tests/unit # Node unit +npm test # cross alias (chama node --test) # E2E -npx playwright install # instala browsers (1a vez) -npx playwright test # roda suite E2E -npx playwright test --ui # modo interativo -npx playwright show-report # abre relatorio ultimo run +npx playwright install # instala browsers (1a vez) +npx playwright test # roda suite E2E +npx playwright test --ui # modo interativo +npx playwright show-report # abre relatorio ultimo run + +# Rust opt-in +(cd rust && maturin develop --release) # builda extensão nativa no venv +python -m pytest tests/python/test_native.py # cobre o caminho nativo # git/PR git checkout -b feat/- -gh pr create --fill # usa template de PR -gh run watch # acompanha CI do branch atual +gh pr create --fill # usa template de PR +gh run watch # acompanha CI do branch atual ``` Adapta os comandos pra stack real (`pnpm`, `yarn`, `bun`, `dotnet`, `python`, `go`).