Agentic Task System (ats)

Seu gerenciador de tarefas é a melhor memória de agente que você não está usando.

ats é um servidor MCP e CLI que mantém o contexto de agentes de IA nos sistemas de tarefas que você já mantém — TickTick, Taskmaster, Beads, Obsidian, Notion, GitHub, Airtable, Google, ou vários ao mesmo tempo por meio do adaptador composto. Ele recupera tarefas, notas, decisões e runbooks relevantes com proveniência e pode gravar resultados de volta quando o adaptador ativo suporta gravações. Funciona com Claude Code, Claude Desktop, Cursor e qualquer cliente MCP.

Adaptador, não migração. Seu aplicativo de tarefas, repositório ou vault permanece autoritativo. O ATS mapeia essa fonte para um contrato de tarefa comum; caches opcionais e índices vetoriais melhoram a recuperação, mas nunca se tornam um segundo registro que as pessoas precisam editar. É tarefa-primeiro: a tarefa é a espinha dorsal, enquanto material de apoio, como issues do GitHub e especificações do Notion, é recuperado como contexto por trás dela.

Duas camadas, um CLI: tarefas e um grafo de conhecimento. A camada de tarefas é baseada em registros de propósito — cada entrada vive nos projetos e campos de um backend, e esse backend permanece autoritativo. Uma camada baseada em registros estruturalmente não pode conter a outra coisa que agentes acumulam: conhecimento durável escrito de qualquer fonte, sobre assuntos mistos, em um único espaço. A camada de grafo de conhecimento — ats kg (kg = knowledge graph) — é a resposta do ATS exatamente para isso: fatos sujeito–predicado–objeto com proveniência e validade temporal, propostos por agentes de qualquer lugar (uma chamada, uma tarefa, um repositório, um chat), ratificados por um humano e consultados em um único lugar, independentemente de qual backend o trabalho ao redor vive. O armazenamento embutido é incorporado e sem dependências. Para um motor de grafo dedicado, a combinação recomendada é Graphiti como servidor de banco de dados de grafo e LadybugDB como banco de dados de grafo embutido: ats kg export --cypher emite um script carregável pelo LadybugDB (--dialect neo4j|falkordb para os motores de servidor, re-executável), e ats kg export --graphiti emite JSONL de episódios com o registro de proveniência para um pipeline de ingestão do Graphiti.

npm install -g @reneza/ats-cli @reneza/ats-adapter-ticktick
ats config use ticktick
ats auth login
ats find "deployment runbook"

Um ats find em GitHub + Notion + TickTick. O ATS classifica os ramos de recuperação disponíveis com RRF e retém a proveniência dos resultados.

Arquitetura e limites de confiança

O ATS separa o registro autoritativo da maquinaria de recuperação ao redor dele:

AI client or operator
        |
        | local stdio, or token-gated HTTP when self-hosted
        v
ATS CLI / MCP server
        |
        +-- Core: task contract, links, lifecycle, ledger, events
        +-- Retrieval: keyword + native + optional dense branches -> RRF
        |
        v
Adapter boundary (auth, mapping, reads, patch-style writes)
        |
        +-- TickTick / Notion / GitHub / Airtable / Google
        +-- Obsidian / Taskmaster / Beads / OKF files
        |
        +-- derived retrieval state
            corpus cache + optional Qdrant/Ollama index

• O backend permanece autoritativo. O ATS não pede que usuários editem um banco de dados de memória duplicado. Gravações passam pelo adaptador ativo, que possui autenticação específica do backend, mapeamento de campos e links profundos.
• O estado de recuperação é derivado, não canônico. O Core mantém um cache de corpus de cinco minutos por padrão. A recuperação densa é opcional: adaptadores podem fornecer embeddings, e o adaptador de referência TickTick pode usar Qdrant mais Ollama. Sem vetores, ramos de palavras-chave e nativos do adaptador ainda são executados.
• Credenciais permanecem na fronteira do adaptador. Um adaptador composto delega autenticação a cada filho e não armazena credencial adicional entre fontes. Seus filhos ainda executam dentro de um único processo ATS; isso é separação de roteamento, não isolamento de processo. O stdio local não expõe uma porta MCP. O blueprint hospedado adiciona um gateway de token portador, serviços privados Qdrant/Ollama e um backend de demonstração público separado para o painel do operador opcional.
• O Core relata as falhas que consegue ver. Falhas de ramos de recuperação e de corpus composto de nível superior retornam degraded e warnings. Caminhos de omissão conhecidos dentro de fallbacks de adaptadores são destacados em Tradeoffs e limites.
• Mudanças de estado são rastreáveis. Resultados carregam proveniência da fonte; find --explain expõe contribuições RRF; gravações usam semântica de patch, e gravações suportadas podem reter imagens anteriores para desfazer.

O cache de corpus pode conter registros completos de tarefas; o log de consultas contém texto de busca; o livro-razão de ações pode conter imagens anteriores de gravações; e payloads Qdrant podem conter texto de tarefas e metadados além de embeddings. O ATS não aplica criptografia em nível de aplicação ou redação em tempo de execução a essas cópias. Escopar acesso ao host, backups, retenção e implantação à sensibilidade dos sistemas de tarefas subjacentes. Veja recuperação, integridade de estado e o guia de implantação para o comportamento exato.

Opções de implantação

Modo	Recuperação	Fronteira de confiança e operações
Stdio local	Recuperação por palavras-chave/nativa por padrão; recuperação densa apenas quando o adaptador a fornece	O endpoint MCP não é exposto à rede. Chamadas de adaptadores ainda podem alcançar seus sistemas de origem; credenciais e arquivos de cache permanecem na máquina que executa o ATS.
Adaptador composto	Um corpus filho combinado; o Core classifica ramos de palavras-chave e busca nativa unificada, com RRF entre os ramos disponíveis. O composto atualmente não expõe busca vetorial filha.	Cada filho possui sua autenticação e mapeamento, mas executa no mesmo processo ATS. Uma falha de corpus filho de nível superior é relatada como degradada; veja as lacunas de fallback conhecidas abaixo.
Blueprint hospedado	Recuperação por palavras-chave/nativa mais serviços privados Qdrant/Ollama	Um gateway MCP de token portador e um backend separado opcional de painel do operador são públicos; Qdrant e Ollama permanecem na rede de serviços privados. Qdrant/Ollama têm discos, enquanto arquivos de runtime ats-mcp são efêmeros por padrão. Você opera rotação de tokens, persistência, backups, disponibilidade e custo de hospedagem.

“Sem migração” significa sem segunda fonte de verdade. Não significa zero armazenamento derivado.

Como se compara

Abordagem	Registro autoritativo	Estado adicional	Recuperação
CLAUDE.md / arquivos de memória	Markdown mantido para o agente	Os próprios arquivos	Busca de arquivo inteiro ou específica do harness
Serviço de memória separado	Banco de dados específico do agente	Um corpus e caminho de ingestão para manter	Específico do produto
Conector de backend simples	Aplicativo de tarefas, repositório ou vault de origem	Geralmente nada além do estado do conector	Busca direta ou busca nativa do backend
ATS	Aplicativo de tarefas, repositório ou vault de origem	Cache, estado de consulta/ação/evento; índice vetorial derivado opcional	Palavras-chave + nativa + recuperação densa opcional, RRF, proveniência, contexto tipado

O ATS é uma boa escolha quando o contexto operacional já vive em sistemas de tarefas ou ferramentas de trabalho conectadas e agentes precisam de recuperação classificada e rastreável entre eles. Se Markdown limpo já é a fonte completa de verdade e o carregamento de arquivo inteiro permanece pequeno, um fluxo de trabalho nativo de arquivos pode ser mais simples.

O que você obtém

• Um barramento bidirecional. O agente lê os campos de tarefa que um adaptador fornece; onde o adaptador suporta gravações, ele grava resultados de volta onde você os verá.
• Relevância na primeira busca. Ramos orientados por capacidade — busca por palavras-chave e nativa do adaptador, mais recuperação densa quando disponível — são fundidos com RRF e proveniência para reduzir loops repetidos de busca-e-refinamento. Cada find carrega um veredito de confiança do acordo entre ramos (--min-sources N é o portão de correspondência), --project o vincula a um projeto, um cache de corpus desatualizado responde imediatamente enquanto atualiza em segundo plano, e uma correspondência exata vazia (notes find, search, get) responde com os itens mais próximos em vez de nada.
• Gravações que sobrevivem a tentativas e concorrência. update --append / --prepend adicionam ao corpo que já existe; --if-match <contentHash> só é aplicado enquanto o corpo está inalterado; create --if-absent e --idempotency-key fazem uma criação repetida retornar o que a primeira produziu. Requisições HTTP compartilhadas têm prazos e respeitam cancelamento. Leituras repetem falhas transitórias; mutações repetem apenas rejeições explícitas de limite de taxa, então falhas ambíguas não reproduzem uma gravação.
• Links tipados duráveis. Um agente anexa um link decision / depends-on / output / supersedes; um agente posterior em um contexto novo o recebe via ats context. A transferência vive no aplicativo de tarefas, não em um log de chat.
• Contexto de execução. ats intent captura resultado/porquê/quando-concluído; ats lifecycle impede que contexto desatualizado direcione o trabalho atual; ats security registra decisões de permitir/negar com escopo para clientes cooperantes; ats ledger registra o que um agente fez e se a tarefa avançou; ats promote transforma exploração em uma meta comprometida; ats hierarchy evaluate verifica se o trabalho local ainda suporta seu pai.
• Eventos limitados. ats events watch --json emite NDJSON determinístico task.created/updated/completed/..., com spool 0600 e recuperação pendente/ack e IDs de deduplicação estáveis. O ATS apenas emite observações — um consumidor ainda avalia intenção, validade e segurança antes de agir.
• Grafo de tarefas para agentes. Tarefas se tornam nós estruturados com arestas de prova, gravação de volta, revisão, ciclo de vida e links, em vez de texto de memória de forma livre; veja docs/task-graph-for-agents.md.
• Uma camada de fatos. ats kg mantém conhecimento durável sujeito–predicado–objeto ao lado das tarefas: agentes propõem (um tripleto, ou um lote JSONL com --file), um humano ratifica (o único caminho de gravação), e ats kg ask responde com pontuação lexical determinística, um veredito de confiança e proveniência completa — sem LLM, sem servidor de grafo, um arquivo somente-anexação que viaja com ats state export. Um portão responde antes que qualquer coisa seja encenada: uma duplicata é um no-op, uma contradição precisa de --supersedes ou --additive, um fato que o revisor recusou precisa de --acknowledge-rejected (saída 4); ats kg pending mostra ao revisor o que cada proposta faria. Retração e superação fecham o intervalo de validade de um fato em vez de deletá-lo, --as-of responde o que o armazenamento acreditava então, ats kg history mostra a cadeia de um fato, ats kg nodes mostra o que o armazenamento sabe sobre quem, ats context carrega os fatos sobre uma tarefa, --semantic adiciona o embedder do adaptador como um ramo denso opt-in, e ats kg export fala LadybugDB/Kùzu, Neo4j, FalkorDB e Graphiti.
• Transferência de índice de sessão. Navegadores de sessão de agentes de codificação podem manter análises brutas de transcrições enquanto o ATS armazena o resumo durável vinculado à tarefa; veja docs/agent-session-index.md.

Metadados de execução gerenciados pelo ATS podem ser codificados no corpo da tarefa, com links tipados sob ## Related e fontes consultadas sob ## References. Helpers gerenciados são projetados para preservar linhas e links criados por humanos; update --content substitui o corpo completo, então chamadores que adicionam a um corpo usam --append / --prepend, apresentam o contentHash que leram com --if-match e verificam o resultado. npm run prove:intent executa uma prova sintética determinística do caminho de contexto de execução.

Para automação confiável e fluxos de atualização, veja Confiabilidade do CLI: paginação com escopo, requisições limitadas, chaves de repetição/retomada limitadas por payload e confirmações de fatos revisadas.

Fluxo de trabalho mínimo neutro de adaptador

1. Selecione e verifique um adaptador: ats config use <adapter>, autentique conforme descrito no README dele e execute ats doctor.
2. Recupere o conjunto de trabalho: ats find "deployment runbook" --json classifica os ramos disponíveis desse adaptador e retém a proveniência.
3. Inspecione o item autoritativo e seu contexto: ats context <project> <task> usa o contrato comum de adaptador e não exige uma camada de notas específica do adaptador.
4. Anexe contexto de execução durável: ats intent set <project> <task> --outcome "..." --done-when "a,b" e ats link add <src-project> <src-task> <dst-project> <dst-task> --type depends-on.
5. Verifique o handoff montado: execute novamente ats context <project> <task> para ler de volta decisões vinculadas, dependências, prova, estado do ciclo de vida e resultados de recuperação relevantes.
6. Grave pelo adaptador ou aplicativo de origem e leia de volta. Mantenha o backend autoritativo atualizado para que o próximo agente receba estado durável em vez de um handoff apenas de chat.

Implante você mesmo

O painel do operador opcional é um aplicativo web estático voltado para celular, implantável no Cloudflare Pages. O blueprint fornecido do Render cria o gateway/servidor MCP, além dos serviços privados Qdrant e Ollama.

Após a implantação, copie o ATS_MCP_TOKEN gerado automaticamente na aba Environment do serviço ats-mcp, aponte seu cliente MCP para https://<your-mcp-url>/mcp com o cabeçalho Authorization: Bearer <ATS_MCP_TOKEN> e defina TICKTICK_ACCESS_TOKEN para ler suas tarefas reais. Prefere sua própria máquina ou uma VPS? Mesmas peças como contêineres Docker simples — veja o guia de implantação.

Adaptadores disponíveis

Conectores de backend permitem que um agente alcance Notion, GitHub e sistemas de tarefas, mas o acesso sozinho não fornece uma resposta classificada para uma pergunta como "o que eu sei sobre a migração de autenticação?" O ATS adiciona uma camada comum de recuperação: o adaptador composto combina corpora filhos instalados, define namespaces para seus IDs de projeto, une resultados de pesquisa nativa suportados e permite que o Core classifique os ramos disponíveis com proveniência. Cada filho lê suas próprias credenciais, mas todos os filhos configurados executam no mesmo processo do ATS.

Adaptador	Fonte autoritativa	Notas de recuperação ou gravação
ticktick	TickTick OpenAPI v1	Pesquisa por palavra-chave/nativa funciona sem vetores; Qdrant + Ollama opcionais adicionam recuperação densa.
obsidian	Vault Markdown local	Nativo de arquivos, gravações em estilo patch preservam frontmatter desconhecido.
okf	Pacote Markdown do Open Knowledge Format	Pacote local.
taskmaster	.taskmaster/tasks/tasks.json local	Estado de tarefas local ao repositório.
beads	Beads local ao repositório via bd --json	Estado de tarefas local com reconhecimento de dependências.
airtable	Airtable REST API (tabela = projeto)	Acesso à API com escopo do adaptador.
google	Google Sheets / Docs / Slides	Somente leitura.
notion	Bancos de dados e páginas do Notion	Acesso com escopo de integração.
github	Issues e discussões do GitHub	Acesso com escopo de repositório.
composite	Backends filhos instalados	Combina corpora filhos, define namespaces para IDs de projeto, une resultados de pesquisa nativa e roteia gravações; não é um armazenamento de registros independente e atualmente não expõe embeddings filhos.
things / apple-notes / google-tasks	—	Lista de desejos, não implementado.

Autenticação e mapeamento por adaptador vivem no README de cada pacote. PRs são bem-vindos — faça o scaffold e verifique contra o contrato:

ats adapter new linear              # writes a contract-complete skeleton
ats adapter test ./ats-adapter-linear   # pass/fail/skip per contract check

Beads em cada repositório

Execute o ATS dentro do repositório que contém .beads; o nome do diretório é o ID de projeto padrão. Para endereçar outro repositório explicitamente, defina a raiz e o ID de projeto para esse comando:

cd /path/to/my-repo
ats config use beads
export ATS_AGENT_ID=worker-a BEADS_ACTOR=worker-a
ats tasks ready --json
ats update my-repo ISSUE --claim
ats link add my-repo ISSUE my-repo PREREQUISITE --type depends-on --native --dry-run

Use o mesmo nome de worker para ATS_AGENT_ID e BEADS_ACTOR; o Beads verifica novamente o ator que reivindica quando uma issue reivindicada é concluída.

De outro diretório, use ATS_ADAPTER=@reneza/ats-adapter-beads ATS_BEADS_ROOT=/path/to/my-repo ATS_BEADS_PROJECT_ID=my-repo ats tasks ready --json. Trabalho pronto contribui com um ramo RRF nomeado; reivindicações e gravações de dependências nativas usam o gate de revisão existente. Veja o guia do adaptador Beads para identidades de worker, semântica de dependências e a prova real de CLI.

Tradeoffs e limites

• A atualização depende do adaptador. O cache de corpus do Core tem um TTL padrão de cinco minutos. O comportamento de sincronização do backend, a paginação e a inclusão de trabalho concluído variam por adaptador; o ATS não promete leituras em tempo real universais. ats cache sync atualiza o cache sob demanda (compatível com cron) — incrementalmente quando o adaptador implementa bulkFetchDelta(), como uma nova busca completa caso contrário.
• A recuperação densa adiciona infraestrutura. Qdrant e Ollama podem melhorar a recuperação semântica, mas adicionam trabalho de indexação, persistência, recursos e backup. A linha de base find ainda retorna resultados por palavra-chave/nativos quando vetores não estão disponíveis, embora um ramo vetorial tentado possa degradar a resposta; operações somente vetoriais hybrid e similar ainda exigem essa infraestrutura.
• O contrato comum é intencionalmente pequeno. A interface do adaptador define seis métodos de armazenamento mais hooks de ciclo de vida de autenticação, enquanto a cobertura prática de gravação, campos mais ricos e pesquisa nativa variam. Verifique o README do adaptador antes de assumir paridade entre backends.
• Resultados degradados ainda são resultados parciais. O ATS relata ramos do Core com falha ou timeout, fontes de corpus descartadas — incluindo falhas por projeto dentro de uma busca composta de fallback e buscas de projetos do TickTick — e fontes de pesquisa nativa que um backend não conseguiu ler. O chamador ainda deve decidir se contexto parcial é aceitável; warnings diz o que está faltando, não se isso importou.
• A busca composta não é deduplicação semântica. ats dedup é um comando de análise separado. A identidade de fusão tem namespace por backend (<backend>:<taskId>), então IDs brutos idênticos de backends diferentes permanecem resultados distintos; tarefas semanticamente duplicadas ainda aparecem separadamente até você vinculá-las.
• O blueprint hospedado é uma implantação de referência, não um serviço gerenciado. Um token de portador concede toda a superfície de ferramentas do MCP; o blueprint não fornece escopos por usuário ou por ferramenta, RBAC multi-tenant, alta disponibilidade ou SLA.
• O estado de runtime do ATS hospedado é efêmero por padrão. O blueprint persiste Qdrant e Ollama, mas não monta um disco para ats-mcp; seu cache, log de consultas, ledger de ações e before-images de desfazer, spool de eventos e metadados de sincronização de vetores desaparecem em um reinício ou reimplantação.
• Eventos são observações, não autorização. ats events watch pode relatar mudanças de tarefas, mas um consumidor ainda deve avaliar intenção, validade e segurança antes de tomar uma ação externa.
• A camada de fatos é lexical por padrão e controlada por humanos. ats kg ask é pontuação determinística de palavras-chave com proveniência e veredito de confiança; --semantic adiciona o embedder do adaptador ativo como um ramo denso opcional e precisa de um. Nada chega ao armazenamento de fatos sem ratificação humana — uma rajada de propostas de agentes espera revisão por design — e nada que duplique, contradiga ou repita um fato negado chega à fila de revisão sem dizer isso.
• A política do ATS não é uma sandbox. A CLI aplica os metadados de aprovação declarados — uma gravação cujo alvo define intent.approvalRequired ou lista a ação em security.approvalRequiredFor entra em ats review em vez de chegar ao backend (ATS_REVIEW_ALL=1 controla toda gravação) — mas isso protege apenas o caminho de gravação do próprio ATS. ats security check permanece um ponto de decisão em nível de aplicativo para clientes cooperativos, e nada aqui intercepta acesso a shell, sistema de arquivos, rede, modelo ou segredos fora do ATS. Um cliente chamando um adaptador diretamente contorna o gate da CLI.

Verificação e evidência operacional

O benchmark de recall sintético de 50 perguntas compara memórias e consultas idênticas entre ATS e Engram v2.2.1:

Caminho de recuperação	Recall@5
ATS somente palavra-chave	12/50 (24%)
ATS denso local + esparso, RRF híbrido	47/50 (94%)
Engram SQLite FTS5, all padrão	20/50 (40%)
Engram SQLite FTS5, any	32/50 (64%)

Engram e ATS híbrido ambos recuperaram todos os alvos de título exato e consulta curta. Este pequeno fixture escrito pelo autor testa perguntas naturais brutas sobre dez memórias de decisão distintas; não estabelece superioridade geral do produto. O resultado híbrido requer embeddings locais, embora não precise de banco de dados vetorial ou chave de modelo hospedado. Dataset, saída bruta, falhas e etapas de reprodução estão vinculados acima.

• CI executa o gate completo do repositório no Node 20 e 22: lint, verificações de reivindicação pública, verificações de PII, testes de unidade, provas de adaptador e intenção, e o benchmark de progresso.
• O gate de segurança de publicação escaneia tanto a superfície do repositório quanto os tarballs de pacotes npm em busca de segredos, caminhos pessoais, padrões de dados pessoais configurados e termos de denylist configurados localmente. Ele protege superfícies de publicação. Em runtime, o adaptador composto pode adicionalmente aplicar níveis de confiança por backend com padrões de redação configurados — uma gravação roteada para um filho "trust": "public" que corresponde a um padrão é bloqueada, não silenciosamente removida (veja o README do composto). Essa tela protege o caminho de gravação composto do próprio ATS; não é prevenção geral de perda de dados.
• Testes e convenções de integridade de estado cobrem gravações em estilo patch, preservação de campos desconhecidos, mapeamento explícito de store para Task, proveniência de resultados e contribuições RRF explicáveis.
• Comportamento de recuperação documenta os ramos do Core, o cache de corpus, orçamentos de tempo, falha graciosa de ramos, registro de uso e o que afeta a latência.

Esses gates verificam o comportamento do repositório; não são uma certificação de disponibilidade de produção ou segurança.

Superfície da CLI

# Lifecycle
ats init [adapter]                  # select an adapter and run a health check
ats config use <adapter>            # switch the active adapter
ats auth login                      # delegate login to the active adapter
ats doctor                          # inspect adapter and service health

# Retrieval  (any read command takes --json for piping to jq / agents)
ats find <query> [--explain]       # parallel + RRF + provenance + confidence verdict — DEFAULT
ats find <query> --project <id|name>   # bind retrieval to a project (--projects a,b for several)
ats find <query> --min-sources 2   # keep only results two branches agree on
ats find <query> --fresh           # refresh a stale corpus cache before answering
ats open <project> <task>          # open any adapter item by explicit ids
ats context <project> <task>       # task + valid linked/retrieved context
ats link list <project> <task>     # list portable typed links
ats hybrid <query>                 # dense+sparse retrieval when embeddings exist
ats similar <id>                   # related items when embeddings exist

# Notes-layer shortcuts (currently TickTick and Obsidian)
ats get <id-or-title> [--extract raw|json|yaml]
ats url <id-or-title>              # paste-ready note cross-reference
ats links <project> <task>         # resolve deep-links in a note body

# Authoring
ats create "<title>" [--content ..][--project <id>]
ats create <project> "<title>" --if-absent --idempotency-key <k>   # never a duplicate on retry
ats update <project> <task> [--content ..][--title ..]
ats update <project> <task> --append "- 2026-09-05: shipped" --if-match <contentHash>   # add to the body; write only if unchanged

# Agent execution context (portable across adapters)
ats intent set <project> <task> --outcome ".." --done-when "a,b"
ats promote <src-proj> <src-task> <target-proj> --outcome ".." --done-when "a,b"
ats hierarchy set <project> <task> --kind task
ats hierarchy evaluate <project> <task>
ats lifecycle set <project> <task> --status active --valid-until 2026-12-31
ats link add <src-proj> <src-task> <dst-proj> <dst-task> --type decision --dry-run --explain
ats graph <project> <task> --depth 3 --max-nodes 500
ats context <project> <task>
ats snapshot <project> <task> --depth 3 --max-nodes 500  # content-addressed context with completeness
ats history <project> <task>                   # revisions and field-level changes
ats history <project> <task> --restore <revision> --dry-run

# Facts layer (proposed by agents, ratified by you)
ats kg propose "Acme GmbH" "prefers" "invoices as PDF" --domain sales --source "call 2026-08-01"
ats kg propose "Acme GmbH" "prefers" "invoices as XML" --domain sales --supersedes <fact-id>  # replaces, in one ratification
ats kg propose --file facts.jsonl --domain sales   # one JSON object per line, every line through the gate
ats kg propose "Acme GmbH" "signed" "renewal" --source task://<project>/<task> --tier action-record
ats kg pending                                     # what each queued proposal would do to the graph
ats review approve <id> && ats kg ratify --all     # approval comes from someone other than the proposer
ats kg verify                                      # recheck every fact's source; exit 2 when one is gone or changed
ats kg ask "what does Acme prefer" --domain sales --json            # + confidence.verdict
ats kg ask "what does Acme prefer" --domain sales --as-of 2026-06-30 # what the store believed then
ats kg ask "invoices" --center "Acme GmbH" --semantic               # anchored on one entity, embedder-backed
ats kg nodes acme                                  # what the store knows about whom
ats kg history <fact-id>                           # events and supersession chain
ats kg export --cypher > facts.cypher      # load into LadybugDB / Kùzu, full provenance on every fact
ats kg export --dialect falkordb           # openCypher for FalkorDB / Neo4j, re-runnable
ats kg export --graphiti > episodes.jsonl  # Graphiti episodes with the provenance record
ats kg export --cypher --include-retracted # closed facts too, with tInvalid and who closed them
ats ledger record <project> <task> --action release.verified --advanced true
ats ledger list --actor-kind agent --session <id>   # who acted, agent or human, in which session
ats ledger verify                                   # hash-chained ledger; prints head for --expect-head
ats security set <project> <task> --trust trusted --allow-actions read --allow-resources task:self
ats security check <project> <task> --action read --resource task:self --reason "load context"
ats events watch --json            # NDJSON observations; never launches agents

# Ops
ats create --input task.json --dry-run       # strict JSON file, or --input - for stdin
ats batch changes.jsonl --dry-run             # validate a mutation batch
ats batch changes.jsonl --journal run.jsonl   # apply and resume by stable item id
ats state doctor                              # validate local schemas and file permissions
ats state import bundle.json --force --dry-run
ats auth status --non-interactive             # bounded to 15s; override with --timeout-ms
ats tasks completed 30 --projects <id> --require-complete   # every completion in the window, paged
ats review list                 # writes staged by approvalRequired targets
ats review approve ID && ats review apply --all
ats cache sync                  # refresh the corpus cache (find also refreshes a stale one in the background)
ats cache status                # age, stale / servable / revalidating
ats bench run
ats bench score
ats bench progress --json
ats bench analyze-usage --days 7
npm run prove:intent
npm run prove:taskmaster
npm run prove:beads
npm run prove:progress

Gravações de tarefas revisadas vinculam a aprovação ao payload exato em stage e verificam a revisão atual da tarefa antes de aplicar. Apenas um processo pode reivindicar um item. Inspecione ats review list --all após um apply interrompido: itens applying ou failed exigem verificação do backend antes de propor um novo stage. Aprovações mais antigas sem digests de payload também devem ser colocadas em stage e aprovadas novamente.

Para automação que exige uma leitura completa, use ats find QUERY --require-complete --fresh --json. Resultados desatualizados, degradados ou explicitamente incompletos mantêm sua saída JSON e saem com código 2; leituras comuns preservam seu comportamento de saída permissivo existente. O Doctor suporta a mesma opção estrita e limita cada sonda: ats doctor --timeout-ms 1000 --require-complete --json. A importação de estado valida conteúdos de arquivo reconhecidos e quaisquer checksums fornecidos mesmo com --dry-run, antes de gravar qualquer arquivo.

Use de qualquer cliente MCP (Claude Code, Claude Desktop, Cursor, Windsurf, OpenCode)

@reneza/ats-mcp expõe o adaptador ativo como um conjunto de ferramentas abrangendo recuperação, CRUD e contexto de execução (find, get_task, create_task, set_task_intent, add_task_link, resolve_task_links, context_for_task, record_action, undo_write, poll_task_events e mais). Para Claude Code, isso fornece contexto persistente entre sessões sem substituir o sistema de tarefas como fonte de verdade; caches opcionais e índices vetoriais permanecem estado de recuperação derivado.

O ATS fala MCP sobre stdio, então qualquer cliente que possa iniciar um servidor MCP stdio funciona. Apenas o arquivo de configuração e a chave de wrapper diferem; o binário (ats-mcp) e seu env ATS_ADAPTER são os mesmos em todos os lugares.

Cliente	Onde a configuração vive	Chave de wrapper
Claude Code	claude mcp add (abaixo)	n/a
Claude Desktop	claude_desktop_config.json	mcpServers
Cursor	~/.cursor/mcp.json	mcpServers
Windsurf	~/.codeium/windsurf/mcp_config.json	mcpServers
OpenCode	opencode.json	mcp (formato difere, abaixo)

# Claude Code
claude mcp add ats -e ATS_ADAPTER=@reneza/ats-adapter-ticktick -- ats-mcp

// Claude Desktop / Cursor / Windsurf — identical `mcpServers` shape
{
  "mcpServers": {
    "ats": { "command": "ats-mcp", "env": { "ATS_ADAPTER": "@reneza/ats-adapter-ticktick" } }
  }
}

// OpenCode (opencode.json) — local stdio server, note `command` is an array
{
  "mcp": {
    "ats": {
      "type": "local",
      "command": ["ats-mcp"],
      "environment": { "ATS_ADAPTER": "@reneza/ats-adapter-ticktick" },
      "enabled": true
    }
  }
}

Instale o binário em PATH primeiro (npm i -g @reneza/ats-cli), ou use um caminho absoluto para ats-mcp se seu cliente não herdar seu PATH de shell.

Convenções

• Projeto Wiki. Um projeto designado (padrão Permanent Notes) mantém conhecimento durável; outros mantêm tarefas efêmeras.
• Notas de dados do agente = uma nota cujo corpo possui um bloco cercado json / yaml block, extracted via ats get <title> --extract json.
• Referências cruzadas = links profundos nativos do adaptador — gere com ats url <title>, não escreva manualmente.
• Padrão completo: docs/wiki-conventions.md.

Integridade do estado

Testes do ATS gerenciam reescritas de metadados para preservação de campos criados por humanos, exigem mapeamento explícito de armazenamento para Task, e carregam proveniência de resultados (sources, find --explain). A cobertura e o comportamento de atualização bruta permanecem específicos do adaptador. Uma barreira de segurança de publicação (check-no-pii.mjs) falha a compilação quando padrões cobertos de dados pessoais aparecem em superfícies de repositório ou pacote. Nota completa: docs/state-integrity.md.

Para o modelo operacional do lado do agente, veja docs/task-graph-for-agents.md: o texto da tarefa é a projeção humana, mas a camada de execução precisa de links estruturados, comandos de prova, requisitos de revisão e alvos de gravação de volta.

Trabalhando no ATS

Contribuições são bem-vindas — correções de bugs e especialmente novos adaptadores sob packages/adapter-*. Veja CONTRIBUTING.md para a configuração de desenvolvimento e o padrão de adaptador, e AGENTS.md se você dirige um agente de codificação sobre o repositório. Trabalhando no código-fonte, pi-codegraph dá ao seu agente um grafo de chamadas do monorepo — o padrão de adaptador e o raio de impacto de uma mudança central — para que ele pare de reler toda a árvore a cada sessão.

Lançamentos e licença

v0.17.0 adiciona recuperação de Beads prontos com consciência de bloqueio, reivindicações atômicas nomeadas, gravações de dependências nativas e verificações reais de concorrência de CLI. Também corrige a seleção de desfazer nomeada e atualiza dependências compatíveis. Histórico completo: CHANGELOG.md.

MIT. Veja LICENSE.

Se o ATS for útil, considere um ⭐ — isso ajuda outros a encontrá-lo.