Records

O plugin Records acompanha os tipos de coisa de que os seus Blueprints (os planos) são feitos: critérios de aceitação e casos de teste para software, personagens para um livro, hipóteses para uma pesquisa, e as decisões que uma equipe toma pelo caminho. O plugin só conhece registros; a raiz declara quais tipos tem, como tipos de registro, e os registros de cada tipo são encontrados, verificados, numerados e listados em toda a raiz. Um registro não é um Blueprint: nunca é um item de coleção, nunca está no índice. O plugin só muda a forma (um rótulo adicionado, renumerado ou retirado, uma lista escrita em uma região própria), nunca uma palavra que você escreveu. Desligado por padrão; eidos plugin enable records o liga. Desligado, os registros são lidos como as listas simples que são e os baseados em arquivos ficam nas suas pastas.

No navegador

Records, uma atividade na barra de atividades: Overview (cada tipo com os seus rótulos, onde vivem os seus registros, os seus campos e a sua contagem, e depois as listas que esperam rótulos), Waiting com a sua contagem (enquanto um tipo tiver status), cada tipo de registro com a sua contagem, as visões salvas de cada tipo, Waiting for labels e Records settings no pé. O + do seu cabeçalho cria um tipo de registro novo.
Um tipo com Show in the sidebar ganha também uma entrada própria na visão Root, sob Records, com a sua contagem: uma raiz de software mostra Acceptance criteria, uma raiz de livro Characters.
Cada tipo tem uma tabela em /p/records/<type>: o rótulo, o texto, o Blueprint onde ele se encontra, a seção e uma coluna por campo, mais Status, Signed off e Tasks onde o tipo os usa. Cada coluna se ordena pelo cabeçalho; uma caixa de busca fica à frente dos filtros por Blueprint, por seção e por cada campo, todos guardados no endereço da página, e Save as view salva um filtro como visão compartilhada ou local. Uma linha abre o seu Blueprint em um modal, rolado até o registro. O menu de uma linha oferece Open, Open in its own page, Remove label e Delete record (perguntado uma vez), e em um tipo com status, Confirm e um submenu Status.
No editor ao vivo, o menu Turn into de uma lista oferece cada tipo com um padrão de rótulo, que rotula cada item da lista numerado depois dos rótulos que já estão no documento, e Plain list (remove labels), que os retira. Nenhum muda uma palavra. Link to a record, no menu de inserção, encontra um registro rotulado pelo rótulo ou pelas palavras e escreve o link.
Um link para um registro é desenhado como o título do Blueprint e o rótulo, com as palavras do registro ao passar o mouse. Um link cujo rótulo não existe é desenhado no tom de erro.
A página de configurações lista cada tipo de registro como um cartão, com Edit e um botão para retirá-lo; New record type abre o mesmo formulário a partir da página de configurações, do Overview e do + da atividade.

Tipos de registro

Um tipo de registro é um nome, um título, um padrão de rótulo, alguns campos e onde vivem os seus registros. O formulário pede:

Name: como a página o chama (Acceptance criteria). O nome para os comandos é derivado dele e mostrado (criterion).
Label: como cada registro é numerado, com {n} onde vai o número: AC{n} rotula AC1, AC2 e assim por diante, com um exemplo ao vivo enquanto você digita. Deixe vazio para registros que têm nome em vez de número, como personagens.
Where they live: In document lists, cada registro um item de lista dentro de um Blueprint, ou One file each, em uma pasta do tipo. Quando já existem registros do tipo, isso fica como está.
Show in the sidebar: uma entrada própria na visão Root.
Fields: os detalhes que cada registro leva, cada um com um nome, um tipo (Text, Choice com as suas opções, Link, Number ou Yes or no) e se é Required.

As configurações do ciclo de vida, mais abaixo, estão no mesmo formulário. Pelo terminal, configure:type escreve as mesmas configurações do mesmo jeito:

eidos records configure:type add criterion --title "Acceptance criteria" --label "AC{n}" --field "status:list:met|unmet" --sidebar

--field "name:type[:options|…][:required]" aceita text, list, link, number ou checkbox, e se repete, substituindo os campos. Retirar um tipo com registros escritos precisa de --force; os seus registros ficam como listas simples, ou na sua pasta.

Registros em um documento

Um registro em linha é um item de lista que começa com o rótulo do seu tipo em negrito, onde quer que esteja em um Blueprint. Os seus campos são a linha recuada abaixo, pares name: value separados por ·:

## Acceptance criteria

- **AC6:** A root with no collections checks clean.
  status: met · test: [check.test.ts](../../cli/test/check.test.ts)

Todo Blueprint que já escreve **AC1:** à mão é lido como está, e também um rótulo intercalado entre dois (AC2b). Um modelo também pode marcar uma seção para um tipo: em Framework Settings → Templates, a opção Records de uma seção escreve  no modelo, e cada item do primeiro nível das listas dessa seção em um Blueprint criado a partir dele passa a ser um registro do tipo, com rótulo ou sem. É assim que se encontra um tipo com nome, como Characters. A marca é só do modelo; um Blueprint nunca a carrega. Quando uma seção está marcada e os itens de um Blueprint existente ali ainda não têm rótulo, o Overview oferece Label n items, que não muda nada até você aceitar.

Os rótulos seguem em sequência dentro do seu Blueprint, de 1 a n sem lacunas. Um registro novo pega o número seguinte. Retirar um (Remove label, Delete record, eidos records unlabel ou remove) renumera os que vêm depois, e cada link para eles, em qualquer arquivo da raiz, acompanha. Rótulos fora de sequência são relatados, com uma correção Renumber.

Registros como arquivos

Um tipo com One file each guarda um arquivo markdown por registro em uma pasta da raiz declarada como do tipo (owned_by: "@records/<type>", com o nome do tipo a menos que você passe --folder). O frontmatter tem o rótulo, o title (as palavras que uma lista mostra), os blueprints a que serve por id e os campos por nome; o corpo são notas. Os rótulos desse tipo seguem em sequência em toda a sua pasta, e cada arquivo é renomeado com o seu rótulo, a menos que seja numerado por ids (abaixo).

Linkar um registro

Faça um link para um registro como para qualquer parte de um documento: um link markdown padrão para o arquivo do seu Blueprint, com o rótulo como fragmento.

See [Validate a Root AC6](../cli-core/check.md#ac6), and [Login AC1](#ac1) in this file.

O link funciona em qualquer lugar onde markdown funciona, no GitHub também. A verificação do núcleo resolve o caminho, e mover o Blueprint o reescreve como reescreve qualquer link. O plugin verifica o fragmento, relata um rótulo que não existe e reescreve o fragmento e o rótulo nas palavras do link quando o registro é renumerado. Escreva as palavras do link como o título do Blueprint e o rótulo; Link to a record do editor o escreve para você. Na linha de comando, um registro é nomeado <blueprint>/<label> (B-SHS2/AC6, o Blueprint por id ou por caminho) ou <path>#<label>.

O ciclo de vida de um registro

Um tipo pode dar aos seus registros um ciclo de vida. Cada parte fica desligada até o tipo ligá-la, no formulário do tipo de registro ou com configure:type, então um tipo que não usa nenhuma é lido e se comporta como um simples.

Status: as etapas por que passa um registro, cada uma em uma de três categorias: esperando por quem decide, confirmado ou fechado (--status Open:waiting --status Mitigated:confirmed --status Accepted:closed). New records start as nomeia o primeiro (--default-status). Os registros em um status de espera formam a fila Waiting, na atividade Records e com eidos records --waiting.
Aprovação (--sign-off): confirmar um registro anota quem o confirmou e quando, como confirmed e confirmed_by ao lado do seu status; sair da categoria confirmada apaga os dois. Só uma pessoa aprova. Um agente propõe e deixa o registro em espera, e só confirma um --as a pessoa que o resolveu na conversa.
List on documents (--listed, tipos baseados em arquivos): cada Blueprint a que um registro serve mostra os registros do tipo em uma lista, mantida em dia em uma região records:list que o plugin escreve, onde o modelo do Blueprint a põe, ou então sob um cabeçalho com o nome do tipo no pé do corpo:
```

- [ ] [RSK-F36 The index drifts from the files](../risk/rsk-f36-the-index-drifts-from-the-files.md) · Open · @claude

```
O plugin a escreve depois de cada mudança; nunca digite dentro dela.
Link to tasks (--tasks, tipos baseados em arquivos): um registro nomeia as tarefas que o realizam (--task <id>), e a página de cada tarefa mostra os registros que a nomeiam.
Numeração (tipos baseados em arquivos): In order (--numbering sequential, o padrão) rotula os registros de 1 a n e renumera depois que um sai. Unique ids (--numbering ids) dá a cada registro um id como as tarefas recebem, com as letras que você escolher antes do hífen (--id-prefix RSK dá RSK-F36). Um id nunca é renumerado, e um id alterado (eidos records set RSK-F36 --id RSK-DRIFT) mantém o anterior como alias que continua a encontrá-lo. Escolha ids quando várias pessoas adicionam registros em branches diferentes, onde dois próximos números colidiriam no merge.

eidos records configure:type add risk --mode file --numbering ids --id-prefix RSK \
  --status Open:waiting --status Mitigated:confirmed --status Accepted:closed \
  --sign-off --listed --tasks

Guardar decisões

Um registro de decisões é o uso mais simples de tudo o que vem acima: um tipo de registro baseado em arquivos com ciclo de vida, um arquivo por decisão, esperando até uma pessoa confirmá-la, listado nos Blueprints para os quais foi tomada e ligado às tarefas que ela afeta.

eidos records configure:type add decision --mode file --numbering ids --id-prefix D \
  --status Proposed:waiting --status Confirmed:confirmed --status Rejected:closed --status Superseded:closed \
  --sign-off --listed --tasks
eidos records add B-SHS2 decision "Cache the index in memory" --task T-4KQ7 --notes "Why, and what else was weighed" --as claude
eidos records confirm D-7M2P --as grace

--notes escreve o corpo do registro: o porquê, o que mais foi pesado, o que ela descarta. Um agente registra uma decisão que tomou por conta própria como si mesmo e a deixa esperando por uma pessoa.

Em disco

.eidos/plugins/records/settings.yaml, compartilhado: types, cada um com name, title, label, mode, sidebar, folder para um tipo baseado em arquivos e fields (cada um com name, type, options e required), mais statuses, default_status, sign_off, listed, tasks, numbering e id_prefix onde o tipo os usa. A página de configurações e configure:type o escrevem; nunca o edite à mão.
A pasta de um tipo baseado em arquivos na raiz, declarada owned_by: "@records/<type>": um arquivo markdown por registro. A raiz →
Os registros em linha vivem nos próprios Blueprints, como os seus itens de lista. Uma região records:list em um Blueprint é do plugin.

Pelo terminal

eidos records                                       # every record, by type; --type, --blueprint, --where field=value, --search, --waiting, --task, --json
eidos records types                                 # the types: labels, fields, mode, and count
eidos records show B-SHS2/AC6                       # one record; <path>#<label>, or a file-based record by its label
eidos records add B-SHS2 criterion "A root with no collections checks clean." --field status=met
eidos records add B-SHS2 risk "The index drifts from the files" --task T-4KQ7 --as claude   # a file-based record serving the blueprint
eidos records set RSK-F36 --status Mitigated --as grace   # --field name=value, --for, --task, --id; into a confirmed status signs it off
eidos records confirm RSK-F36 --as grace            # to the type's first confirmed status; a person signs off
eidos records label B-SHS2 --section "Acceptance criteria" --type criterion --dry-run   # the labels it would add; no word changes
eidos records unlabel B-SHS2/AC6                    # a plain list item again; the labels after it renumbered, links following
eidos records remove B-SHS2/AC6                     # the record taken out; the labels after it renumbered, links following
eidos records renumber --dry-run                    # labels back in sequence, in one blueprint or every one
eidos records project                               # write every records:list region that drifted again; or one blueprint
eidos records configure:type set criterion --no-sidebar   # add|set|remove; --dry-run, --json

Cada comando aceita --json. Uma escrita é assinada com --as <alias>, senão com EIDOS_USER, senão com o usuário que está agindo.

Um agente adiciona um registro com eidos records add, retira um com eidos records remove e nunca numera rótulos à mão: o plugin os mantém em sequência e os links para eles em dia. Ele escreve a frase do registro com as palavras do dono, deixa a linha de campos para valores e rotula uma lista existente só quando pedem.

O que a verificação relata

Tudo são avisos: records/label-gap (rótulos fora de sequência, um rótulo intercalado ou um rótulo repetido; Renumber corrige, como eidos records renumber), records/label-duplicate (um rótulo repetido em um Blueprint, ou em dois arquivos de um tipo), records/field-required (um campo obrigatório vazio), records/field-option (o valor de um campo Choice fora das suas opções), records/field-type (um campo Number ou Yes or no com outra coisa), records/reference-missing (um link cujo rótulo o seu Blueprint não tem), records/type-unknown (uma seção de modelo marcada para um tipo que a raiz não declara), records/blueprint-missing (um registro baseado em arquivo que serve a um Blueprint que a raiz não tem), records/task-missing (um registro que nomeia uma tarefa que o backlog não tem) e records/list-stale (uma região records:list que já não é o que dizem os seus registros; a correção a escreve de novo). Desligado de novo, nada muda em um Blueprint e nada do plugin roda.