daniloaguiarbr · daniloaguiarbr · Jun 4, 2026 · Jun 4, 2026 · Jun 4, 2026 · Jun 4, 2026
diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md
@@ -0,0 +1,70 @@
+---
+name: Bug report
+about: Report a reproducible bug or unexpected behavior
+title: "[BUG] "
+labels: ["bug", "triage"]
+assignees: []
+---
+
+## Summary
+
+<!-- One-paragraph description of the bug -->
+
+## Reproduction
+
+### Environment
+- sqlite-graphrag version: `sqlite-graphrag --version` output
+- Operating system: (e.g. Fedora 41, Ubuntu 24.04, macOS 15, Windows 11)
+- Architecture: (e.g. x86_64, aarch64)
+- MSRV toolchain: `rustc --version` (when built from source)
+- Database mode: (default `graphrag.sqlite` in CWD, or custom via `--db`)
+
+### Steps
+1.
+2.
+3.
+
+### Expected
+<!-- What you expected to happen -->
+
+### Actual
+<!-- What actually happened, with full stderr and exit code -->
+
+```
+$ sqlite-graphrag ...
+[PASTE OUTPUT HERE]
+```
+
+## Logs
+
+```bash
+# Set SQLITE_GRAPHRAG_LOG_FORMAT=json to get machine-parseable logs
+SQLITE_GRAPHRAG_LOG_FORMAT=json SQLITE_GRAPHRAG_LOG_LEVEL=debug sqlite-graphrag <cmd> 2>&1 | jaq '.'
+```
+
+Paste relevant trace here:
+
+```
+[PASTE LOGS HERE]
+```
+
+## Cross-References
+- Related gap: (if any, e.g. G28, G29)
+- Related memory in GraphRAG: (if you have access, e.g. `g28-process-proliferation`)
+- Related discussion: (GitHub issue, Discord, email, etc.)
+
+## Acceptance Criteria
+
+This bug is considered FIXED when:
+- [ ] The exact reproduction steps above no longer exhibit the broken behavior
+- [ ] A regression test exists in `tests/` or inline `#[cfg(test)] mod tests`
+- [ ] `cargo test --all-features` passes with the new test
+- [ ] `CHANGELOG.md` has a `### Fixed` entry referencing the issue
+- [ ] `gaps.md` is updated if the bug was not previously tracked
+
+## Out of Scope
+
+Please do NOT use this template for:
+- Feature requests: use `.github/ISSUE_TEMPLATE/feature_request.md`
+- Questions / support: open a GitHub Discussion instead
+- Security disclosures: follow `SECURITY.md` policy
diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml
@@ -0,0 +1,14 @@
+blank_issues_enabled: false
+contact_links:
+  - name: sqlite-graphrag documentation
+    url: https://github.com/daniloaguiarbr/sqlite-graphrag/blob/main/docs/AGENTS.md
+    about: Read the full agent integration guide, command reference, and exit code table before opening an issue.
+  - name: sqlite-graphrag GitHub Discussions
+    url: https://github.com/daniloaguiarbr/sqlite-graphrag/discussions
+    about: Open-ended Q&A, integration help, and architecture discussions live here. Use Discussions instead of Issues for "how do I…" questions.
+  - name: sqlite-graphrag Security Advisories
+    url: https://github.com/daniloaguiarbr/sqlite-graphrag/security/advisories
+    about: Report security vulnerabilities privately via GitHub Security Advisories. Do NOT open a public issue for suspected CVEs.
+  - name: sqlite-graphrag Roadmap and CHANGELOG
+    url: https://github.com/daniloaguiarbr/sqlite-graphrag/blob/main/CHANGELOG.md
+    about: Check the CHANGELOG for known issues already fixed in recent releases before opening a duplicate report.
diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md
@@ -0,0 +1,65 @@
+---
+name: Feature request
+about: Suggest a new subcommand, flag, or behavior change
+title: "[FEATURE] "
+labels: ["enhancement", "triage"]
+assignees: []
+---
+
+## Summary
+
+<!-- One-paragraph description of the proposed feature -->
+
+## Problem Statement
+
+<!-- What user-facing problem does this solve? Quantify if possible. -->
+
+## Proposed Solution
+
+### CLI Surface
+<!-- New subcommand or new flag with example invocations -->
+```bash
+sqlite-graphrag <new-subcommand> --<new-flag> <value>
+```
+
+### JSON Contract (if applicable)
+```json
+{
+  "field": "value"
+}
+```
+
+### Memory / GraphRAG Impact (if applicable)
+- New memory type?
+- New entity type?
+- New relation type?
+- New schema migration required?
+
+## Alternatives Considered
+
+<!-- What other approaches did you consider, and why is this one better? -->
+
+## Cross-References
+- Related gap: (if any, e.g. G28-A, G28-B, G28-D)
+- Related PR or issue: (if any)
+- Related external documentation: (e.g. SQLite docs, Claude Code CLI docs, etc.)
+
+## Acceptance Criteria
+
+This feature is considered DONE when:
+- [ ] Subcommand or flag is implemented and exported
+- [ ] JSON Schema updated in `docs/schemas/` for the new output contract
+- [ ] Inline `#[cfg(test)] mod tests` cover the new behavior
+- [ ] Integration test in `tests/` covers end-to-end usage
+- [ ] `CHANGELOG.md` has a `### Added` entry referencing the issue
+- [ ] `docs/AGENTS.md`, `docs/HOW_TO_USE.md`, `docs/COOKBOOK.md` updated (EN + PT-BR)
+- [ ] `skill/sqlite-graphrag-{en,pt}/SKILL.md` updated to reference the new behavior
+- [ ] `llms.txt`, `llms.pt-BR.txt`, `llms-full.txt` updated
+- [ ] All 10 validation commands pass: `cargo check`, `clippy`, `fmt --check`, `doc`, `test`, `audit`, `deny check`, `publish --dry-run`, `llvm-cov`, `package --list`
+
+## Out of Scope
+
+Please do NOT use this template for:
+- Bug reports: use `.github/ISSUE_TEMPLATE/bug_report.md`
+- Questions / support: open a GitHub Discussion instead
+- Security disclosures: follow `SECURITY.md` policy
diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md
@@ -0,0 +1,78 @@
+## Description
+
+<!-- Concise summary of the changes -->
+
+## Related Gap or Issue
+
+- Gap: (e.g. G28, G29, G31, G32)
+- Issue: (e.g. #123)
+- Memory: (e.g. `g29-cargo-install-windows-compile-failure`)
+
+## Type of Change
+
+- [ ] Bug fix (non-breaking change that fixes an issue)
+- [ ] New feature (non-breaking change that adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to change)
+- [ ] Documentation update (no code change)
+- [ ] Schema migration (adds a new `V<NNN>__*.sql` file)
+- [ ] Dependency update (Cargo.toml change)
+- [ ] CI / workflow change (`.github/workflows/*.yml`)
+
+## Validation Checklist (REQUIRED)
+
+All boxes must be checked before requesting review.  Use the command as written, do not substitute flags.
+
+- [ ] `cargo fmt --all --check` — clean
+- [ ] `cargo check --all-targets` — zero errors
+- [ ] `cargo clippy --all-targets --all-features -- -D warnings` — zero warnings
+- [ ] `cargo doc --no-deps --all-features` (with `RUSTDOCFLAGS="-D warnings"`) — zero warnings
+- [ ] `cargo test --all-features` — zero failures (test count in description)
+- [ ] `cargo test --test <new-test-file>` (if applicable) — passes
+- [ ] `cargo audit` — zero vulnerabilities
+- [ ] `cargo deny check advisories licenses bans sources` — zero violations
+- [ ] `cargo publish --dry-run --allow-dirty` — zero errors
+- [ ] `cargo package --list` — zero `.profraw`, zero `graphrag.sqlite`
+
+## Documentation Checklist (REQUIRED if code changed)
+
+- [ ] `CHANGELOG.md` (EN) updated with `### Added` / `### Fixed` / `### Changed` / `### Removed` entry
+- [ ] `CHANGELOG.pt-BR.md` updated mirroring the EN entry
+- [ ] `docs/AGENTS.md` updated if JSON contract changed
+- [ ] `docs/AGENTS.pt-BR.md` updated mirroring the EN change
+- [ ] `docs/HOW_TO_USE.md` updated if new flag or subcommand
+- [ ] `docs/HOW_TO_USE.pt-BR.md` updated mirroring the EN change
+- [ ] `docs/COOKBOOK.md` updated with a new recipe if user-visible behavior added
+- [ ] `docs/COOKBOOK.pt-BR.md` updated mirroring the EN change
+- [ ] `docs/MIGRATION.md` updated if breaking change (with rollback section)
+- [ ] `docs/MIGRATION.pt-BR.md` updated mirroring the EN change
+- [ ] `docs/schemas/*.schema.json` updated if JSON contract changed
+- [ ] `docs/CROSS_PLATFORM.md` updated if Windows/macOS/Linux behavior changed
+- [ ] `docs/CROSS_PLATFORM.pt-BR.md` updated mirroring the EN change
+- [ ] `skill/sqlite-graphrag-{en,pt}/SKILL.md` updated if operational behavior changed
+- [ ] `llms.txt`, `llms.pt-BR.txt`, `llms-full.txt` updated
+- [ ] `INTEGRATIONS.md` updated if new external integration
+- [ ] `INTEGRATIONS.pt-BR.md` updated mirroring the EN change
+- [ ] `gaps.md` updated if the gap was previously tracked
+
+## Commit Hygiene (REQUIRED)
+
+- [ ] Commit messages are in English
+- [ ] Commit messages do NOT contain `Co-authored-by:` lines referencing AI agents or bots
+- [ ] Commit messages use the imperative mood ("Add X" not "Added X")
+- [ ] First line of commit message is ≤ 72 characters
+- [ ] Body wraps at 72 characters and explains the WHY
+- [ ] Each commit is atomic (one logical change per commit)
+
+## Test Coverage
+
+- [ ] New unit tests added for new functions
+- [ ] New integration test added in `tests/` for new subcommands
+- [ ] Coverage threshold of 80% maintained (`cargo llvm-cov --text`)
+
+## Risk Assessment
+
+<!-- What could break? What is the rollback plan? -->
+
+## Reviewer Notes
+
+<!-- Anything specific the reviewer should focus on, e.g. performance, security, API compatibility -->
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -128,6 +128,22 @@ jobs:
       - uses: Swatinem/rust-cache@v2
       - run: cargo check --all-features
 
+  # G29 (v1.0.68): cross-compile check to catch HANDLE-type regressions on
+  # Windows before publish.  Host arch on the runner is x86_64, so x86_64-pc-
+  # windows-msvc catches the type check without needing the full Windows
+  # linker (lib.exe) installed.
+  windows-build-check:
+    name: Windows MSVC cross-compile (G29)
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dtolnay/rust-toolchain@stable
+        with:
+          targets: x86_64-pc-windows-msvc
+      - uses: Swatinem/rust-cache@v2
+      - name: cargo check --target x86_64-pc-windows-msvc
+        run: timeout 600 cargo check --target x86_64-pc-windows-msvc --lib --all-features
+
   audit:
     name: Security Audit
     runs-on: ubuntu-latest

diff --git a/.gitignore b/.gitignore
@@ -26,6 +26,7 @@ secrets.toml
 /MEMORY.md
 memory/
 docs_rules/
+docs_prd/
 ralph-loop.local.md
 
 # IDE

diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,12 +1,38 @@
 # Changelog
 
+- Read this document in [Portuguese (pt-BR)](CHANGELOG.pt-BR.md).
+
 All notable changes to this project will be documented in this file.
 
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+_None yet. v1.0.68 is the latest published release; new commits land in this section until the next version is cut._
+
+## [1.0.68] - 2026-06-03
+
+### Fixed
+- `cargo install sqlite-graphrag` broke on Windows with `error[E0308]: mismatched types` in `src/terminal.rs:29` because `HANDLE` in `windows-sys >= 0.59` is `*mut c_void` (was `isize` in 0.48/0.52).  Replaced `handle != 0 && handle as isize != -1` with the type-safe idiom `!handle.is_null() && handle != INVALID_HANDLE_VALUE`.  Also pinned `windows-sys` to `=0.59.0` exact and added CI job `windows-build-check` that runs `cargo check --target x86_64-pc-windows-msvc` on every push (G29).
+- `enrich` and `ingest --mode claude-code|codex` could be invoked in parallel against the same namespace and saturate the host (root cause of the 2026-06-03 276-load-average incident).  Added `lock::acquire_job_singleton` per `(job_type, namespace)` and a new `AppError::JobSingletonLocked { job_type, namespace }` exit-75 error.  A second concurrent invocation now fails fast instead of stacking 4 × N workers × 10 MCP processes (G28-B).
+- `claude_runner::build_claude_command` now respects `SQLITE_GRAPHRAG_CLAUDE_EMPTY_CONFIG_DIR` — when set to an existing empty directory, the subprocess is spawned with `CLAUDE_CONFIG_DIR=<that dir>`, suppressing user-scoped MCP servers and the 8-10-process fan-out they cause.  We deliberately do not pass `--strict-mcp-config` / `--mcp-config '{}'` because [anthropics/claude-code#10787] documents that Claude Code CLI ignores both flags.  `CLAUDE_CONFIG_DIR` is the only mechanism upstream actually honours (G28-A).
+- `retry` module gains a `CircuitBreaker` helper (with `AttemptOutcome::{Success,Transient,HardFailure}` and tests) that `enrich --retry-failed` can use to abort persistent-failure loops.  Transient / rate-limited errors do NOT count toward the threshold, so a provider that recovers is not penalised (G28-D).
+- 3 pre-existing test failures in `src/commands/{history,list,read}.rs` that leaked `SQLITE_GRAPHRAG_DISPLAY_TZ` between parallel test threads and asserted hardcoded `1970-01-01T00:00:00` strings now parse the ISO output via `chrono::DateTime::parse_from_rfc3339` and compare `timestamp()` against `DateTime::UNIX_EPOCH` for timezone-agnostic assertions.  The full test suite is now green on every timezone (`UTC`, `America/Sao_Paulo`, `Europe/Berlin`, etc.) without per-test setup of the env var.
+
+### Added
+- `retry::CircuitBreaker` (struct + `record` / `is_open` / `reset`) — opt-in helper for bounded retry loops.  Rate-limited and timeout errors are explicitly excluded from the failure count.
+- `lock::acquire_job_singleton(job_type, namespace, wait_seconds)` — process-wide singleton for heavy commands.
+- `constants::JOB_SINGLETON_POLL_INTERVAL_MS = 1000` — backing interval for the singleton polling loop.
+- `errors::AppError::JobSingletonLocked { job_type, namespace }` — exit 75, classified as retryable and with localised PT-BR message.
+- CI job `windows-build-check` runs `cargo check --target x86_64-pc-windows-msvc --lib --all-features` to catch Windows regressions before publish.
+- `tests/terminal_compile_windows.rs` — regression test that the public `terminal::init_console` and `should_use_ansi` stay callable; on Windows it also references the type-safe HANDLE check.
+- `lock::tests` — 3 unit tests covering singleton namespace sanitisation, second-invocation blocking, and per-namespace isolation.
+
+### Changed
+- `enrich` emits a `tracing::warn!` (visible with `-v`) when `llm_parallelism > 4` recommending combining with `SQLITE_GRAPHRAG_CLAUDE_EMPTY_CONFIG_DIR` to keep subprocess fan-out manageable (G28-D, non-breaking).
+- `Cargo.toml`: `windows-sys` pinned to `=0.59.0` exact (was range `0.59`).
+
 ## [1.0.67] - 2026-06-01
 
 ### Added

diff --git a/CHANGELOG.pt-BR.md b/CHANGELOG.pt-BR.md
@@ -10,6 +10,30 @@ e este projeto adere ao [Semantic Versioning](https://semver.org/lang/pt-BR/spec
 
 ## [Sem Versão]
 
+_Nenhuma ainda. v1.0.68 é a versão publicada mais recente; novos commits entram nesta seção até a próxima versão ser cortada._
+
+## [1.0.68] - 2026-06-03
+
+### Corrigido
+- `cargo install sqlite-graphrag` quebrava no Windows com `error[E0308]: mismatched types` em `src/terminal.rs:29` porque `HANDLE` em `windows-sys >= 0.59` é `*mut c_void` (era `isize` em 0.48/0.52).  Substituímos `handle != 0 && handle as isize != -1` pelo idiom type-safe `!handle.is_null() && handle != INVALID_HANDLE_VALUE`.  Também fixamos `windows-sys` em `=0.59.0` exato e adicionamos o job de CI `windows-build-check` que roda `cargo check --target x86_64-pc-windows-msvc` em todo push (G29).
+- `enrich` e `ingest --mode claude-code|codex` podiam ser invocados em paralelo no mesmo namespace e saturar a máquina (causa raiz do incidente de load average 276 em 2026-06-03).  Adicionamos `lock::acquire_job_singleton` por `(job_type, namespace)` e a nova variante `AppError::JobSingletonLocked { job_type, namespace }` com exit 75.  Uma segunda invocação concorrente agora falha rápido em vez de empilhar 4 × N workers × 10 processos MCP (G28-B).
+- `claude_runner::build_claude_command` agora respeita `SQLITE_GRAPHRAG_CLAUDE_EMPTY_CONFIG_DIR` — quando definido para um diretório existente e vazio, o subprocesso é iniciado com `CLAUDE_CONFIG_DIR=<esse dir>`, suprimindo servidores MCP do escopo user e a fan-out de 8-10 processos que eles causam.  Deliberadamente NÃO passamos `--strict-mcp-config` / `--mcp-config '{}'` porque [anthropics/claude-code#10787] documenta que o Claude Code CLI ignora ambas as flags.  `CLAUDE_CONFIG_DIR` é o único mecanismo que o upstream honra (G28-A).
+- O módulo `retry` ganha um helper `CircuitBreaker` (com `AttemptOutcome::{Success,Transient,HardFailure}` e testes) que `enrich --retry-failed` pode usar para abortar loops de falha persistente.  Erros transient / rate-limited NÃO contam para o threshold, então um provider que se recupera não é penalizado (G28-D).
+- 3 falhas de teste pré-existentes em `src/commands/{history,list,read}.rs` que vazavam a env var `SQLITE_GRAPHRAG_DISPLAY_TZ` entre threads de teste paralelos e afirmavam strings hardcoded `1970-01-01T00:00:00` agora parseiam a saída ISO via `chrono::DateTime::parse_from_rfc3339` e comparam `timestamp()` contra `DateTime::UNIX_EPOCH` para asserções timezone-agnostic.  A suíte de testes completa agora fica verde em todo fuso horário (`UTC`, `America/Sao_Paulo`, `Europe/Berlin`, etc.) sem necessidade de setup por teste da env var.
+
+### Adicionado
+- `retry::CircuitBreaker` (struct + `record` / `is_open` / `reset`) — helper opt-in para loops de retry limitados.  Erros rate-limited e timeout são explicitamente excluídos da contagem.
+- `lock::acquire_job_singleton(job_type, namespace, wait_seconds)` — singleton de processo para comandos pesados.
+- `constants::JOB_SINGLETON_POLL_INTERVAL_MS = 1000` — intervalo de polling do singleton.
+- `errors::AppError::JobSingletonLocked { job_type, namespace }` — exit 75, classificado como retryable e com mensagem PT-BR localizada.
+- Job de CI `windows-build-check` que roda `cargo check --target x86_64-pc-windows-msvc --lib --all-features` para capturar regressões Windows antes do publish.
+- `tests/terminal_compile_windows.rs` — teste de regressão para `terminal::init_console` e `should_use_ansi`; no Windows também referencia a checagem type-safe de HANDLE.
+- `lock::tests` — 3 testes unitários cobrindo sanitização de namespace, bloqueio da segunda invocação e isolamento por namespace.
+
+### Alterado
+- `enrich` emite `tracing::warn!` (visível com `-v`) quando `llm_parallelism > 4`, recomendando combinar com `SQLITE_GRAPHRAG_CLAUDE_EMPTY_CONFIG_DIR` para manter a fan-out de subprocessos administrável (G28-D, não-breaking).
+- `Cargo.toml`: `windows-sys` fixado em `=0.59.0` exato (era range `0.59`).
+
 ## [1.0.67] - 2026-06-01
 
 ### Adicionado