dev-context-engine 1.26.0

Dev Context Engine — offline context builder for AI coding agents

Dev Context Engine (DCE)

Motor de Contexto para Agentes de IA — consolida conhecimento técnico corporativo e entrega pacotes de contexto estruturados para o Kiro via MCP.

O DCE não é uma base de conhecimento genérica.
O DCE não é um clone de ai-memory.
O produto central é o Context Builder.

---

Status

Item	Valor
Versão	1.26.0 (Sprint 42)
Fase	Pós-1.0 — Sprint 42 concluída; aguardando aprovação para Sprint 43
Licença	MIT
Stack	Python 3.12+, SQLite FTS5, Typer, Rich, PyYAML, Pydantic, MCP SDK

1.26.0: + CONTRIBUTING (PB-106).
1.25.0–1.22.0: dce recent / tools / doctor stats / index --json.
1.21.0–1.0.0: workspace_status, facets, aliases MCP, Windows Releases, Context Builder.
Kiro: docs/Kiro.md · Contribute: CONTRIBUTING.md.

---

Quick start

python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

dce init .
dce index .
dce build "ORA-12541"
dce mcp --path .

Instalação como pacote (quando publicado):

pip install dev-context-engine
dce --version

Distribuição PyPI: dev-context-engine (o nome dce já estava ocupado).
Import e CLI continuam dce. Detalhes: docs/Packaging.md.

Fontes indexadas

Indexer	Default	source_type	On by default?
markdown	docs / README	markdown	yes
adr	docs/adr/**	adr	yes
memory	.dce/memory/**	memory	yes
procedure	.dce/procedures/**, procedures/**, docs/procedures/**	procedure	yes
incident	.dce/incidents/**, incidents/**, docs/incidents/**	incident	yes
snippet	.dce/snippets/**, snippets/**, docs/snippets/**	snippet	yes
jira_import	imports/jira/**	jira	no
jira_rest	Jira REST JQL (env credentials)	jira	no
git	git log (max 200)	git	no

dce index . --source git
dce hooks install .              # optional: post-commit reindex (git only)
dce index . --source jira_rest   # requires JIRA_* env; never required offline
dce build "PAY-7" --source-type git

Jira REST (opcional):

export JIRA_BASE_URL=https://your.atlassian.net
export JIRA_EMAIL=[e-mail]
export JIRA_API_TOKEN=...          # or JIRA_PAT=...
# dce.yaml: indexers.jira_rest.enabled: true
dce index . --source jira_rest

Âncoras extras (opcional em dce.yaml):

retrieval:
  anchors:
    extra_patterns:
      - name: err_code
        pattern: '\b(ERR-\d{4})\b'
        kind: error_code
        case: upper

Kiro / MCP

Adoção rápida: docs/Kiro.md.
Contrato normativo: docs/MCP.md (schema_version: "1").

dce init .
dce index .
dce mcp --path /absolute/path/to/workspace

Exemplo de registro MCP (Kiro / clientes compatíveis):

{
  "mcpServers": {
    "dce": {
      "command": "dce",
      "args": ["mcp", "--path", "/absolute/path/to/workspace"]
    }
  }
}

Tools estáveis: build_context (primária), search_context, search_memory, search_by_issue, search_by_project, search_by_component, search_by_technology, search_by_tag, list_facets, workspace_status, get_document, recent_documents.

Qualidade:

ruff check src tests && ruff format --check src tests
mypy
pytest

---

Visão em uma frase

Quando o Kiro pergunta “já tivemos algo parecido com ORA-12541?”, o DCE monta automaticamente um pacote de contexto com bugs, issues, ADRs, procedimentos, commits e snippets relevantes — de forma offline, rápida e estruturada.

---

Por que existe

Em empresas de software o conhecimento se espalha em Jira, Git, PRs, ADRs, Markdown, wikis e conversas. Em poucos meses ele se perde: investigações se repetem, incidentes voltam e decisões arquiteturais são esquecidas.

O DCE indexa essas fontes e constrói contexto, em vez de apenas “buscar texto”.

---

Arquitetura (visão)

flowchart TB
  subgraph Sources["Fontes"]
    Jira
    Git
    MD[Markdown]
    ADR[ADRs]
    Proc[Procedimentos]
    Inc[Incidentes]
    Snip[Snippets]
  end

  Sources --> Indexers
  Indexers --> FTS[(SQLite FTS5)]
  FTS --> CB[Context Builder]
  CB --> MCP[MCP Server]
  MCP --> Kiro

Detalhes: docs/Architecture.md.

---

Princípios de produto

1. Context Builder primeiro — busca é primitiva; o valor é o pacote consolidado.
2. 100% offline — sem APIs pagas, sem embeddings externos, sem banco vetorial.
3. Kiro-first — MCP com respostas estruturadas; Cursor é só a ferramenta de construção.
4. Indexers independentes — baixo acoplamento; nenhuma fonte depende de outra.
5. Simplicidade operacional — um arquivo SQLite por workspace; CLI + MCP stdio.

---

Documentação

Documento	Conteúdo
Kiro adoption	Setup rápido no Kiro
MCP Contract	Contrato MCP schema_version 1 (Kiro)
Packaging	Build, smoke e publish PyPI
Windows portable	dce.exe ZIP para Windows / Kiro
Release Windows	Tag v* → Release assets + SHA-256
Operations	Runbook operacional local
SLOs	Alvos de latência + dce bench
Release 1.0 Checklist	Gates RC → 1.0.0 + PyPI
Product Vision	Problema, escopo, anti-escopo, discovery
Architecture	Módulos, fluxos, interfaces
Architecture Decisions	Índice de ADRs
Roadmap	Evolução por releases
Product Backlog	Itens priorizados
Sprint 01	Planejamento da primeira sprint
Coding Standards	Padrões de código
Testing Strategy	Estratégia de testes
Release Strategy	Releases e gates
Versioning	SemVer e política de breaking changes
Glossary	Termos do domínio
CHANGELOG	Histórico de mudanças

---

Consumidor principal: Kiro

O DCE será consultado continuamente durante o desenvolvimento no Kiro. Requisitos de experiência:

• Latência previsível (alvo MVP: p95 < 500 ms para build_context em índice local típico)
• Respostas estruturadas (JSON / modelos Pydantic), não prosa
• Ferramentas MCP estáveis e versionadas
• Pacotes de contexto com orçamento de tamanho (evitar inundar o agente)

Ferramentas MCP estáveis (schema_version: "1" — ver docs/MCP.md):

Tool	Papel
build_context	Principal — monta o pacote de contexto
search_context	Busca filtrada no índice
search_memory	Alias tipado — só notas memory
search_by_issue	Alias tipado — chave Jira-like (PAY-123)
search_by_project	Alias tipado — escopo por projeto
search_by_component	Alias tipado — escopo por componente
search_by_technology	Alias tipado — escopo por tecnologia
search_by_tag	Alias tipado — escopo por tag
list_facets	Descobre slugs de project/component/technology/tag
workspace_status	Saúde do workspace (doctor --json)
get_document	Documento completo por ID
recent_documents	Documentos recentes

---

Stack

• Python 3.12+
• SQLite + FTS5 — índice full-text e metadados
• Typer + Rich — CLI
• Pydantic + PyYAML — modelos e configuração
• MCP SDK oficial (mcp) — servidor stdio
• pytest + ruff + mypy — qualidade

---

Requisitos não negociáveis

• Offline completo
• Multiplataforma (macOS, Linux, Windows)
• Baixo uso de CPU/memória
• Sem banco vetorial
• Sem OpenAI / IA externa / APIs pagas

---

Próximo passo

Sprint 42 encerrada. Sprint 43 inicia somente após aprovação explícita.

./scripts/cut_release.sh && git push origin HEAD && ./scripts/cut_release.sh --push
# First PyPI (manual): docs/PublishPyPI.md

Ver: docs/Sprint42.md · CONTRIBUTING.md.

---

Licença

MIT — ver LICENSE.