229 lines
10 KiB
Markdown
229 lines
10 KiB
Markdown
# CLAUDE.md — Contrato Vinculante da Wiki UFO/UAP
|
||
|
||
> Versão `0.1.0` · Última atualização `2026-05-13` · Schema canônico em [`CLAUDE-schema-full.md`](CLAUDE-schema-full.md)
|
||
|
||
Toda agente que tocar este projeto **lê este arquivo no boot**. Operar lendo apenas este contrato é suficiente para tarefas correntes — detalhes de schema vivem em `CLAUDE-schema-full.md`.
|
||
|
||
## 1. Filosofia em uma frase
|
||
|
||
Wiki investigativa estilo **Karpathy LLM Wiki** + **Investigation Bureau** (8 detetives Holmes/Poirot/Dupin/Locard + Schneier/Tetlock/Taleb). Markdown puro, sem RAG, com procedência absoluta de cada claim.
|
||
|
||
## 2. Layout
|
||
|
||
```
|
||
/Users/guto/ufo/
|
||
├── CLAUDE.md ← este arquivo (contrato)
|
||
├── CLAUDE-schema-full.md ← schema completo dos 24 tipos
|
||
├── raw/ ← IMUTÁVEL (115 PDFs + 14 JPG/PNG)
|
||
├── processing/ ← intermediário (PNGs, OCR, vision raw)
|
||
├── wiki/ ← GERADO (documents, pages, entities, tables, images)
|
||
├── case/ ← Investigation Bureau (evidence, witnesses, hypotheses, ...)
|
||
└── scripts/ ← pipelines de ingest, dedup, lint
|
||
```
|
||
|
||
**Regra de ouro:** nada escreve em `raw/`. Referências usam path relativo `../raw/<file>.pdf`.
|
||
|
||
## 3. Idioma — bilíngue EN + PT-BR (português brasileiro)
|
||
|
||
A wiki é **bilíngue** desde o ingest. A mesma chamada Haiku vision gera EN e PT-BR juntos (single pass, preserva contexto visual da imagem).
|
||
|
||
| Categoria de campo | Idioma |
|
||
|---|---|
|
||
| YAML keys | **English** (international standard) |
|
||
| OCR raw text | **Source language only** (verbatim, no translation) |
|
||
| `verbatim_excerpt` (evidence), `verbatim_quotes` (person), `caption_ocr` (image) | **Source language only** |
|
||
| Enums (`page_type`, `content_classification`, `evidence_grade`, `confidence_band`, redaction codes, classification markings) | **English** (universal) |
|
||
| `canonical_name`, technical IDs | **Source language**; aliases array can hold PT-BR forms |
|
||
| Narrative descriptions (`vision_description`, `narrative_summary`, `executive_summary`, `description` in gaps, `definition_short` in concepts, `verdict_rationale` in witnesses) | **Both EN and PT-BR** via sibling fields `vision_description` + `vision_description_pt_br` etc. |
|
||
| Markdown body sections (headings + commentary) | **Both EN and PT-BR** in adjacent sections: `## Vision Description (EN)` then `## Descrição Vision (PT-BR)` |
|
||
|
||
**PT-BR rules:**
|
||
|
||
- Must be **Brazilian Portuguese** (`pt-br`), NOT European Portuguese. Use Brazilian vocabulary and spelling.
|
||
- Preserve UTF-8 accents correctly: `ç`, `ã`, `á`, `é`, `í`, `ó`, `ú`, `â`, `ê`, `ô`, `à`. Never strip accents.
|
||
- When a verbatim quote from the document appears inside a narrative paragraph, keep the **quote** in source language and translate only the surrounding narration.
|
||
- IDs always ASCII-fold (kebab-case without accents). Display fields (`canonical_name`) preserve accents when applicable.
|
||
|
||
Encoding: **always UTF-8**.
|
||
|
||
## 4. Os 24 tipos de markdown
|
||
|
||
| Tipo | Caminho | Owner |
|
||
|---|---|---|
|
||
| `document` | `wiki/documents/<doc-id>.md` | archivist |
|
||
| `page` | `wiki/pages/<doc-id>/p<NNN>.md` | archivist + evidence-officer |
|
||
| `person` | `wiki/entities/people/<id>.md` | profiler |
|
||
| `organization` | `wiki/entities/organizations/<id>.md` | profiler |
|
||
| `location` | `wiki/entities/locations/<id>.md` | archivist |
|
||
| `event` | `wiki/entities/events/<id>.md` | timeline-analyst |
|
||
| `uap_object` | `wiki/entities/uap-objects/<id>.md` | evidence-officer |
|
||
| `vehicle` | `wiki/entities/vehicles/<id>.md` | archivist |
|
||
| `operation` | `wiki/entities/operations/<id>.md` | archivist |
|
||
| `concept` | `wiki/entities/concepts/<id>.md` | archivist |
|
||
| `table` | `wiki/tables/<table-id>.md` | archivist |
|
||
| `image` | `wiki/images/<image-id>.md` | evidence-officer |
|
||
| `evidence` | `case/evidence/<E-NNNN>.md` | evidence-officer |
|
||
| `witness_analysis` | `case/witnesses/<W-NNNN>.md` | witness-officer |
|
||
| `timeline` | `case/timelines/<scope>.md` | timeline-analyst |
|
||
| `hypothesis` | `case/hypotheses/<H-NNNN>.md` | hypothesis-lead |
|
||
| `actor_profile` | `case/profiles/<AP-NNNN>.md` | profiler |
|
||
| `gap` | `case/gaps/<G-NNNN>.md` | archivist + chief-detective |
|
||
| `relation` | `case/connect-the-dots/<R-NNNN>.md` | chief-detective |
|
||
| `case_report` | `case/case-report.md` | case-writer |
|
||
| `residual_uncertainty` | `case/residual-uncertainty.md` | chief-detective |
|
||
| `index` | `wiki/index.md` | archivist |
|
||
| `log` | `wiki/log.md` | archivist (append-only) |
|
||
| (este) | `CLAUDE.md` | chief-detective |
|
||
|
||
Schemas de frontmatter detalhados em [`CLAUDE-schema-full.md`](CLAUDE-schema-full.md).
|
||
|
||
## 5. Frontmatter obrigatório universal
|
||
|
||
Todo arquivo `.md` em `wiki/` e `case/` tem:
|
||
|
||
```yaml
|
||
---
|
||
schema_version: "0.1.0"
|
||
type: <enum> # document | page | person | ... (24 tipos)
|
||
canonical_title: "..." # OU canonical_name (entidades)
|
||
wiki_version: "0.1.0"
|
||
last_ingest: "2026-05-13T14:22:11Z" # OU last_revised
|
||
---
|
||
```
|
||
|
||
## 6. Naming canônico (regex)
|
||
|
||
| Tipo | Regex | Exemplo |
|
||
|---|---|---|
|
||
| `doc_id` | `^[a-z0-9][a-z0-9-]*$` | `dow-uap-d54-mission-report-mediterranean-sea-na` |
|
||
| `page_id` | `^[a-z0-9-]+/p\d{3}$` | `dow-uap-d54-.../p007` |
|
||
| `person_id` | `^[a-z][a-z0-9-]*$` (ASCII-fold) | `j-edgar-hoover` |
|
||
| `event_id` | `^EV-\d{4}-(\d{2}\|XX)-(\d{2}\|XX)-[a-z0-9-]+$` | `EV-2004-11-14-tic-tac-nimitz` |
|
||
| `uap_object_id` | `^OBJ-[A-Z0-9-]+-\d{2}$` | `OBJ-EV2004-NIMITZ-01` |
|
||
| `evidence_id` | `^E-\d{4}$` | `E-0042` |
|
||
| `witness_id` | `^W-\d{4}$` | `W-0007` |
|
||
| `hypothesis_id` | `^H-\d{4}$` | `H-0003` |
|
||
| `table_id` | `^TBL-[A-Z0-9]+-\d{4}$` | `TBL-DOWD54-0003` |
|
||
| `image_id` | `^IMG-[A-Z0-9]+-p\d{3}-\d{2}$` | `IMG-DOWD54-p007-01` |
|
||
| `gap_id` | `^G-\d{4}$` | `G-0012` |
|
||
| `relation_id` | `^R-\d{4}$` | `R-0028` |
|
||
| `actor_profile_id` | `^AP-\d{4}$` | `AP-0001` |
|
||
|
||
### Algoritmo `filename → doc_id`
|
||
|
||
```
|
||
1. Strip extension (.pdf, .jpg, .png)
|
||
2. NFD + remove combining marks (ASCII fold)
|
||
3. Lowercase
|
||
4. Replace whitespace/underscore/non-[a-z0-9-] com "-"
|
||
5. Collapse "-" repetidos
|
||
6. Trim "-" inicial/final
|
||
7. Se começa com dígito, prefixa "doc-"
|
||
```
|
||
|
||
## 7. Wiki-links — 18 namespaces
|
||
|
||
```
|
||
[[doc-id]] → wiki/documents/<doc-id>.md
|
||
[[doc-id/pNNN]] → wiki/pages/<doc-id>/p<NNN>.md
|
||
[[people/<id>]] → wiki/entities/people/<id>.md
|
||
[[org/<id>]] → wiki/entities/organizations/<id>.md
|
||
[[loc/<id>]] → wiki/entities/locations/<id>.md
|
||
[[event/<id>]] → wiki/entities/events/<id>.md
|
||
[[uap/<id>]] → wiki/entities/uap-objects/<id>.md
|
||
[[vehicle/<id>]] → wiki/entities/vehicles/<id>.md
|
||
[[op/<id>]] → wiki/entities/operations/<id>.md
|
||
[[concept/<id>]] → wiki/entities/concepts/<id>.md
|
||
[[table/<id>]] [[image/<id>]] → wiki/tables|images/<id>.md
|
||
[[evidence/<id>]] [[witness/<id>]]
|
||
[[hypothesis/<id>]] [[profile/<id>]]
|
||
[[gap/<id>]] [[relation/<id>]] → case/...
|
||
[[people/...|Grusch]] → custom display text
|
||
```
|
||
|
||
**Backlinks** (`mentioned_in[]` em entidades) são **materializados pelo Lint, NÃO escritos à mão**.
|
||
|
||
## 8. Confidence calibration (Tetlock)
|
||
|
||
| Banda | Faixa | Linguagem permitida |
|
||
|---|---|---|
|
||
| `high` | ≥0.90 | "demonstra", "estabelece" |
|
||
| `medium` | 0.60–0.89 | "sugere fortemente", "indica" |
|
||
| `low` | 0.30–0.59 | "possivelmente", "pode" |
|
||
| `speculation` | <0.30 | "hipótese", "especulação" — sempre rotulado |
|
||
|
||
Toda claim em sumário executivo carrega `confidence_band`.
|
||
|
||
## 9. Classificação de conteúdo (`content_classification`)
|
||
|
||
Array enum em `document` e `page`:
|
||
|
||
- `text-only` · `contains-photos` · `contains-sketches` · `contains-diagrams` · `contains-maps` · `contains-tables` · `contains-signatures` · `contains-stamps` · `redaction-heavy` (>30% redacted) · `mixed` · `blank`
|
||
|
||
Doc-level = união dos valores das páginas.
|
||
|
||
## 10. Procedência (Locard)
|
||
|
||
- Toda `evidence` aponta `source_page` + `bbox` (opcional).
|
||
- Toda claim em entidade tem `mentioned_in[]` com `page_ref`.
|
||
- `chain_of_custody[]` obrigatório em evidence; `custody_gaps[]` explícitos.
|
||
- Grade A → ≥3 custody steps · Grade B → ≥2 · Grade C → ≥1
|
||
|
||
## 11. Operações canônicas
|
||
|
||
1. **INGEST** — PDF → PNG por página → vision Haiku → `page.md` + entity upsert
|
||
2. **LINT** — scan reverso, materializa `mentioned_in[]`, valida wiki-links, reporta orphans
|
||
3. **QUERY** — leitura por wiki-link traversal; nunca via embeddings
|
||
|
||
Log toda operação em `wiki/log.md` (append-only, formato fixo).
|
||
|
||
## 12. Quality gates (chief-detective enforça)
|
||
|
||
Threshold global **0.85** em 6 rubrics no `case-report.md`:
|
||
|
||
1. `chain_of_custody_completeness`
|
||
2. `confidence_calibration_match`
|
||
3. `hypothesis_tournament_discipline` (≥3 hipóteses)
|
||
4. `residual_uncertainty_presence`
|
||
5. `audit_trail_per_claim`
|
||
6. `red_team_pass`
|
||
|
||
Lint adicional **bloqueante**:
|
||
|
||
- Wiki-links resolvem 100%
|
||
- `entity.mentioned_in` ↔ `page.entities_extracted` consistente
|
||
- Nenhum `canonical_name` duplicado sem `disambiguation_note`
|
||
- `pages[]` contínuo `1..page_count` por documento
|
||
|
||
## 13. Triggers de enrichment externo
|
||
|
||
- **≥3 menções OU central claim** → `enrichment_status: deep` (WebSearch + ≥2 `external_sources`)
|
||
- **1-2 menções** → `enrichment_status: shallow` (1 query + knowledge interno)
|
||
- **0 menções** (inferida) → `enrichment_status: none`
|
||
|
||
## 14. Idempotência
|
||
|
||
Re-ingest do mesmo PDF (mesmo `sha256`) atualiza `last_ingest`, preserva `created_at`. Re-lint sobrescreve `mentioned_in[]` mas não duplica.
|
||
|
||
## 15. Escalation
|
||
|
||
Agente encontra:
|
||
|
||
- **Contradição entre evidências grade A/B** → escalar `chief-detective`
|
||
- **Hypothesis sobrevivente com posterior >0.70** → revisão multi-detective
|
||
- **Gap critical** → criar `[[gap/G-NNNN]]` + linkar em `case-report`
|
||
|
||
## 16. Modelo
|
||
|
||
Default para ingest, vision, dedup, lint, enrichment, e geração de markdown: **`claude-haiku-4-5`**.
|
||
|
||
`case-writer` (narrativa Holmes-Watson final) e `chief-detective` (red team review) podem opcionalmente usar Sonnet para qualidade final.
|
||
|
||
## 17. Stack de execução
|
||
|
||
- **PDF → PNG**: `pdftoppm -r 200` (Poppler)
|
||
- **PDF → texto**: `pdftotext -layout`
|
||
- **Vision**: Anthropic SDK Python + Haiku, com prompt caching e `pdf-2025-03-04` beta header se aplicável
|
||
- **Linting**: Python (PyYAML + regex)
|
||
|
||
Scripts em `/Users/guto/ufo/scripts/`.
|