{"id":43426370,"url":"https://github.com/fabriciopsouza/metacognition-framework","last_synced_at":"2026-05-31T04:01:03.393Z","repository":{"id":336078271,"uuid":"1148201718","full_name":"fabriciopsouza/metacognition-framework","owner":"fabriciopsouza","description":"Universal prompt engineering framework for critical AI validation","archived":false,"fork":false,"pushed_at":"2026-05-24T23:45:41.000Z","size":103,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-25T01:33:54.622Z","etag":null,"topics":["ai-validation","business-intelligence","chatgpt","claude","data-integrity","data-science","llm","metacognition","prompt-engineering","python","quality-assurance"],"latest_commit_sha":null,"homepage":"","language":"HTML","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/fabriciopsouza.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-02-02T17:38:38.000Z","updated_at":"2026-05-24T23:45:45.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/fabriciopsouza/metacognition-framework","commit_stats":null,"previous_names":["fabriciopsouza/metacognition-framework"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/fabriciopsouza/metacognition-framework","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabriciopsouza%2Fmetacognition-framework","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabriciopsouza%2Fmetacognition-framework/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabriciopsouza%2Fmetacognition-framework/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabriciopsouza%2Fmetacognition-framework/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fabriciopsouza","download_url":"https://codeload.github.com/fabriciopsouza/metacognition-framework/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fabriciopsouza%2Fmetacognition-framework/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33718446,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-31T02:00:06.040Z","response_time":95,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai-validation","business-intelligence","chatgpt","claude","data-integrity","data-science","llm","metacognition","prompt-engineering","python","quality-assurance"],"created_at":"2026-02-02T19:05:07.645Z","updated_at":"2026-05-31T04:01:03.386Z","avatar_url":"https://github.com/fabriciopsouza.png","language":"HTML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Framework Metacognitivo Agêntico — Genérico e Escalável\r\n\r\n\u003e **Versão:** 1.21.0 · **Base:** pesquisas A0–A3 · **PT-BR** · **CC BY 4.0**\r\n\u003e **Princípio:** o framework é **estritamente agnóstico de domínio** (ADR-010 / Princípio 12). Linguagens, ferramentas, normas setoriais, regulamentações, padrões técnicos, frameworks de validação, regras de negócio — **quaisquer** — são **aplicações/contextos**: não fazem parte do núcleo, **não aparecem hardcoded em prompts/regras/docs do framework** (nem como exemplo). Domínio é **declarado pelo discovery** por projeto. O que o núcleo oferece é **mecanismo genérico**: data integrity, audit trail, validação por risco, traceability, observabilidade — todos no `_shared/`.\r\n\u003e **QA bicelular (v1.12.0 / ADR-011 / Princípio 13):** fluxo do squad tem 6 junções binárias forward-only (J0-J5) com gates declarados em `/handoff` + process-critic adversarial final (qa-critic em subagente isolado) com poder de rewind cascata. TODO QA é adversarial. SUPLANTA × EMENDA política binária.\r\n\u003e **Handoff cross-sessão (v1.13.0 / ADR-012 / Princípio 14):** discovery passo 6(e) declara \"alimenta outra sessão?\"; se SIM, Pacote de handoff obrigatório via J5 (artefato+versão, localização, acesso, prompt pronto-para-colar, pendências). +rules #6 (RCA gate) e #7 (cobertura temporal pós-J4) em qa-critic SKILL.\r\n\u003e **Série \"da prosa ao mecanismo\" (v1.14.x→v1.20.0 / ADR-013..020):** regras críticas que dependiam de boa-vontade do agente ganharam par executável — contrato de skill (`validate_skills.py`), allowlist por efeito (`effect-gate`), telemetria/poda, QA turno-único heterogêneo, sync de repo no boot (`check-repo-sync`) e **agnosticismo do núcleo** (`check_core_agnostic.py`, ADR-020: enforcement do Princípio 12 acima).\r\n\u003e **Runtime + entrega de produto (v1.21.0 / ADR-021..023):** hooks de runtime para digest pré-compaction (`compaction-gate`, ADR-021) e `product_type`/escopo gated por execution-modes (`mission-gate`, ADR-022); e a app de entrega `exemplos/dominio-software/` (ux-designer + evals-engineer, ADR-023) — o framework **culmina em produto** de software/dados; núcleo segue agnóstico (governance/poda já cobertos por high-stakes-gate e pelo campo `classe`).\r\n\r\n## Camadas\r\n```\r\nROTEADOR     AGENT-FRAMEWORK.md (v2.3)   decide o MODO (contexto × complexidade)\r\nNÚCLEO       _shared/                    regras transversais (fonte única)\r\nPROCESSO     .agent/skills/              papéis genéricos: pmo, discovery (+ sub-modo\r\n                                         \"mapeamento de processo\" em v1.6.0), architect,\r\n                                         developer, qa-critic, docops, explorer, _template\r\nCONTRATO     docs/specs/                 requirements.md + validation.md (gate binário)\r\nINFRA        _meta/                      isolamento de subagente, external-access, evals\r\nAPLICAÇÕES   exemplos/README.md          COMO criar aplicações (clonando _template) — vivem FORA do núcleo\r\n```\r\n\r\n## Tudo no núcleo é genérico (ADR-010 / Princípio 12)\r\n**Estritamente agnóstico:** nenhum arquivo de `_shared/`, `.agent/` ou `docs/` (excluindo CHANGELOG histórico e exemplos didáticos rotulados em `docs/specs/exemplos/`) carrega listas hardcoded de produto, norma, convenção ou regra de domínio. O framework sabe **orquestrar, classificar, validar, isolar, rastrear** — para qualquer domínio. Quando há sinal de contexto especializado, **o `discovery` pergunta ao dono** (5 perguntas obrigatórias: regulado/alto-risco/regra-com-semântica/gaps-não-bloqueantes/**alimenta-outra-sessão**); a resposta vai para o `requirements.md`/`research-brief.md` em `## Escopo declarado pelo discovery` e dispara os gates downstream (incluindo Pacote de handoff cross-sessão se item (e) afirmativo — ADR-012 v1.13.0). **Anti-vazamento cross-projeto:** o agente não importa convenção/norma de outra sessão/projeto sem confirmação.\r\n\r\n## Como aplicar a um contexto (escala por clonagem)\r\n1. `cp -r .agent/skills/_template \u003caplicacao\u003e` e preencher só o domínio.\r\n2. Caso concreto → `cp -r docs/specs/_template docs/specs/\u003ccaso\u003e`.\r\n3. Sistema externo? → padrão `_meta/external-access` (MCP).\r\n4. Eval-set (`_meta/eval-template`) — só entra em produção passando.\r\nA aplicação herda `_shared/` automaticamente; mudar regra transversal = editar **um** arquivo.\r\n\r\n## Setup em PC novo (idempotente)\r\n- **Windows:** `pwsh ./bootstrap.ps1` (opcional `-MemoryRepo \"\u003cowner/repo\u003e\"` para sincronizar memória do Claude Code).\r\n- **macOS/Linux:** `./bootstrap.sh` (opcional `--memory-repo \u003cowner/repo\u003e`).\r\n- O script faz git config, garante `gh` CLI autenticado, clona o repo, e opcionalmente clona seu repo privado de memória no path esperado pelo Claude Code. Roda 2x sem destruir nada.\r\n\r\n## Matriz de ambiente\r\n| Recurso | Claude Code / SDK | Chat web |\r\n|---|---|---|\r\n| Ler `_shared/` via filesystem | sim | referência via contexto do Projeto |\r\n| Isolamento real de subagente (explorer) | sim | hats sequenciais simulados |\r\n| Hooks OTel / auditoria | sim | checklist manual |\r\n| Spec, roteamento por confiança, papéis | sim | sim |\r\n\r\n## Papéis (skills do framework)\r\n\r\n| Papel | Quando ativa | Sub-modos |\r\n|---|---|---|\r\n| **pmo** | Entrada padrão · projeto novo · ambiguidade | — |\r\n| **discovery** | Pedido novo/vago · spec rasa | (1) método universal · (2) revisar projeto existente · (3) **mapeamento de processo (v1.6.0)** — para processo de negócio com gatilhos/RACI/handoffs/exceções |\r\n| **architect** | Decisão técnica \u003e 1 arquivo · ADR | — |\r\n| **developer** | Implementação de código/skill/template | — |\r\n| **qa-critic** | Validação adversarial pós-developer | — |\r\n| **docops** | Documentação final pós-aprovação | — |\r\n| **explorer** | Auditoria read-only | — |\r\n\r\n## Papéis emergentes (hats — sem skill nova; ver GUIA-EQUIPE)\r\nskill-librarian · evals-engineer · governance-lead.\r\n\r\n## Documentos (mapa)\r\n- **Comece aqui:** `guia/INSTALAR-NO-VSCODE.md` (instalar) e `guia/SETUP.md` (3 modos).\r\n- **Quem lê o quê:** `guia/ORIENTACAO.md` (humano × IA).\r\n- **Uso diário:** `guia/GUIA-EQUIPE.md` · **Revisar repo:** `guia/COMO-REVISAR-OUTRO-REPO.md`.\r\n- **Git/versão:** `guia/GIT-VERSIONAMENTO.md` · **Referências:** `guia/REFERENCIAS.md`.\r\n- **Versão web:** `guia/web/index.html` (abre no navegador).\r\n- **Prompt do chat web:** `PROMPT-CHAT-WEB-v4.3.md` (raiz) — encarnação do framework para\r\n  ambientes sem filesystem (Claude.ai, Gemini). Mesmos princípios, mesmos resultados,\r\n  papéis e subagentes simulados. Par dos outros load-bearing da raiz (`CLAUDE.md`,\r\n  `AGENTS.md`, `AGENT-FRAMEWORK.md`).\r\n- **Proveniência:** `CHANGELOG.md` (raiz). **Aplicações de domínio:** vivem FORA do núcleo —\r\n  criadas clonando `.agent/skills/_template`. Ver `exemplos/README.md`.\r\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabriciopsouza%2Fmetacognition-framework","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffabriciopsouza%2Fmetacognition-framework","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffabriciopsouza%2Fmetacognition-framework/lists"}