discadmin/disclosure-bureau
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions
disclosure-bureau/CLAUDE.md

10 KiB
Raw Blame History

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

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.

5. Frontmatter obrigatório universal

Todo arquivo .md em wiki/ e case/ tem:

---
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/.