msd-core/docs/pt-BR/reference/state-md.md

Referência do esquema STATE.md

STATE.md é o arquivo de memória viva do projeto do MSD Core — um único documento Markdown que registra em que ponto o projeto se encontra, o que aconteceu por último e o que executar a seguir. Esta página documenta sua estrutura. Consulte o índice da documentação.

---

Visão geral

Todo projeto gerenciado pelo MSD Core mantém um único STATE.md em .planning/STATE.md. Ele é lido no início de todo fluxo de trabalho e escrito após toda ação significativa. O arquivo combina:

• Frontmatter YAML — campos legíveis por máquina consumidos pelo hook de linha de status (parseStateMd) e pelos comandos msd-tools state.
• Corpo Markdown — seções legíveis por humanos cobrindo a posição atual, contexto acumulado, continuidade de sessão e métricas de desempenho.

O arquivo é intencionalmente pequeno (meta: menos de 100 linhas). Ele é um resumo do estado do projeto, não um arquivo histórico.

---

Frontmatter YAML

O frontmatter aparece entre delimitadores --- no início do arquivo. Todos os campos, exceto msd_state_version e status, são opcionais; os campos podem estar ausentes quando seus dados ainda não estão disponíveis.

Exemplo comentado

---
msd_state_version: '1.0'
milestone: v2.0
milestone_name: Code Quality
status: executing

# Campos de ciclo de vida de fase — todos opcionais (adicionados na v1.40.0, issue #2833)
active_phase: "4.5"
next_action: execute-phase
next_phases: ["4.5"]

progress:
  total_phases: 17
  completed_phases: 10
  total_plans: 84
  completed_plans: 47
  percent: 59

# Campos adicionais escritos por syncStateFrontmatter
current_phase: "4"
current_phase_name: Observability
current_plan: "3"
last_updated: "2026-06-01T12:34:56.789Z"
state_head: 4f3c2b1a9e8d7c6b5a4f3e2d1c0b9a8f7e6d5c4b
last_activity: "2026-06-01"
stopped_at: "Phase 4 P3 execution complete"
paused_at: null
---

Referência de campos

Campo	Tipo	Quando populado	Finalidade
msd_state_version	string ('1.0')	Sempre	Versão do esquema; escrito na primeira chamada state.* por syncStateFrontmatter.
milestone	string (ex.: v2.0)	Quando um milestone está configurado	Versão do milestone atual, lida da configuração do projeto.
milestone_name	string	Quando um milestone está configurado	Rótulo legível do milestone (ex.: Code Quality).
status	string	Sempre	Estágio atual do ciclo de vida. Normalizado por normalizeStateStatus() — veja valores de status.
active_phase	string (ex.: "4.5")	Um comando do orquestrador está em andamento nesta fase	O número da fase atualmente sendo processada. Definido como null entre fases.
next_action	string	Ocioso, com um comando recomendado	O slash command a executar a seguir: discuss-phase, plan-phase, execute-phase ou verify-phase. Definido como null quando um orquestrador está em andamento ou nenhuma recomendação está disponível.
next_phases	array YAML flow (ex.: ["4.5"])	Acompanha next_action	Os IDs de fase aos quais o next_action se aplica (tipicamente 1–2 entradas). Definido como null nas mesmas condições que next_action.
progress.total_phases	inteiro	Quando dados de fase estão disponíveis	Número total de fases no milestone atual, derivado do ROADMAP.md e do diretório de fases.
progress.completed_phases	inteiro	Quando dados de fase estão disponíveis	Número de fases que têm todos os resumos de planos em disco (ou seja, todos os planos concluídos).
progress.total_plans	inteiro	Quando arquivos de plano existem	Soma de todos os arquivos de plano nas fases do milestone atual.
progress.completed_plans	inteiro	Quando arquivos de resumo existem	Soma dos resumos de planos concluídos (um SUMMARY.md por plano executado).
progress.percent	inteiro 0–100	Quando dados de progresso estão disponíveis	Progresso do milestone na dimensão de fases (min(completed_plans/total_plans, completed_phases/total_phases)). A barra de progresso da linha de status é renderizada somente quando este campo está presente — sua ausência suprime a barra.
current_phase	string	Quando uma fase está em execução	Número da fase extraído do campo Current Phase: do corpo.
current_phase_name	string	Quando uma fase tem nome	Nome da fase extraído do campo Current Phase Name: do corpo.
current_plan	string	Quando um plano está em andamento	Número do plano extraído do campo Current Plan: do corpo.
last_updated	timestamp ISO-8601	Sempre (na escrita)	Timestamp da última chamada a syncStateFrontmatter; escrito por realClock.nowIso().
state_head	string (40-char sha)	On write, when the project's own git repo resolves	Full commit sha STATE.md was written against (#2573). Omitted entirely outside a git repo, or when the resolved repo is not the project's own — an unverifiable stamp degrades to absent rather than asserting provenance the file does not have. Recomputed on every write and never carried forward.
last_activity	string	Quando definido no corpo	Data da última atividade, extraída do campo Last Activity: do corpo.
last_activity_desc	string	Quando definido no corpo	Descrição da última atividade, extraída do campo Last Activity Description: do corpo.
stopped_at	string	Quando um ponto de parada foi registrado	Descrição da última ação concluída; limitada à seção ## Session do corpo para evitar correspondência com prosa de arquivo.
paused_at	string	Quando o projeto está pausado	Descrição de forma livre do ponto de pausa; ausente ou null quando não pausado.

Cardinalidade dos campos

Campo	Cardinalidade
msd_state_version	one
milestone	optional
milestone_name	optional
current_phase	optional
current_phase_name	optional
current_plan	optional
status	one
stopped_at	optional
paused_at	optional
last_updated	one
last_activity	optional
last_activity_desc	optional
state_head	optional
progress.total_phases	optional
progress.completed_phases	optional
progress.total_plans	optional
progress.completed_plans	optional
progress.percent	optional

Valores de status

normalizeStateStatus() em msd-core/bin/lib/state-document.cjs mapeia o texto bruto do corpo para estes valores canônicos:

Valor canônico	Texto correspondente (sem diferenciação de maiúsculas/minúsculas)
discussing	contém discussing
planning	contém planning ou ready to plan
executing	contém executing, in progress ou ready to execute
verifying	contém verif
completed	contém complete ou done
paused	contém paused ou stopped, ou paused_at está presente
unknown	nenhuma das anteriores

Quando um comando do orquestrador está em andamento, a convenção (issue #2833) é escrever o estágio do ciclo de vida diretamente em status:

Comando	status durante a execução
/msd-discuss-phase	discussing
/msd-plan-phase	planning
/msd-execute-phase	executing
/msd-verify-work	verifying

Ciclo de vida do status (ADR-2207)

The Status field follows a strict lifecycle across phase and milestone boundaries:

Valor	Escrito por	Significado
Ready to plan	completePhaseCore (non-last phase)	Next phase is ready for planning
All phases complete	completePhaseCore (last phase)	All phases done; milestone awaiting formal close
<version> milestone complete	milestoneCompleteCore	Milestone formally closed and archived
Awaiting next milestone	milestoneCompleteCore	Terminal/archived state

Phase-completion verbs never write Milestone complete (the overloaded bare value was removed in #2204 per ADR-2207 to decouple phase-level writes from milestone termination).

---

Cenas de renderização da linha de status

formatMsdState() em hooks/msd-statusline.js lê o frontmatter analisado e emite a primeira cena correspondente. Se nenhum campo novo do ciclo de vida se aplicar, a renderização cai para o formato original byte a byte, inalterado desde a v1.38.x.

Cena	Gatilho	Exemplo de exibição
1. Fase ativa	active_phase está populado	v2.0 [██░░░░░░░░] 20% · Phase 4.5 executing
2. Ocioso, próximo recomendado	active_phase é null E tanto next_action quanto next_phases estão populados	v2.0 [██░░░░░░░░] 20% · next execute-phase 4.5
3. Milestone completo	percent é 100 OU completed_phases == total_phases	v2.0 [██████████] 100% · milestone complete
4. Fallback padrão	Nenhuma das anteriores corresponde	v1.9 Code Quality · executing · ph 1/5 (formato existente)

Prioridade de cena: quando active_phase e next_action estão populados, a Cena 1 prevalece — um orquestrador está em andamento, portanto uma "próxima recomendação" seria enganosa. Essa prioridade é imposta pela ordem de verificação em formatMsdState() e coberta pelo conjunto "scene priority" em tests/msd-statusline.test.cjs.

A barra de progresso ([██░░░░░░░░] 20%) é anexada ao segmento do milestone somente quando progress.percent está presente no frontmatter; ausente significa sem barra.

---

Restrições de análise do frontmatter

O hook de linha de status usa análise baseada em regex (sem biblioteca YAML completa), portanto as seguintes restrições se aplicam. Elas são testadas em tests/msd-statusline.test.cjs.

1. O frontmatter deve começar no primeiro caractere do arquivo. Qualquer coisa — incluindo comentários — acima do --- de abertura invalida a correspondência. A linha --- de abertura deve ser exatamente isso, sem espaços no final.

2. Comentários dentro de blocos aninhados não são suportados. O analisador do bloco progress: requer que a próxima linha seja [ \t]+\w+:. Inserir um # comment entre progress: e sua primeira chave quebra a correspondência e a barra desaparece. Qualquer documentação pertence ao corpo do STATE.md, não dentro dos blocos do frontmatter.

3. O formato primário de next_phases é flow de linha única. O analisador tenta primeiro next_phases: ["4.5", "4.6"]. Sequências em bloco (- 4.5\n- 4.6) também são analisadas, mas são menos confiáveis para renderização da linha de status. Prefira flow de linha única para next_phases para manter o analisador baseado em regex previsível. Se muitas fases candidatas precisarem ser registradas para fins de documentação, armazene-as no corpo do STATE.md.

Se uma mudança futura substituir o analisador de regex por uma biblioteca YAML completa, essas restrições poderão ser relaxadas e os testes atualizados adequadamente.

---

Seções do corpo Markdown

O corpo (tudo após o --- de fechamento) segue o template em msd-core/templates/state.md. As seções padrão são:

Referência do Projeto

Aponta para .planning/PROJECT.md. Contém:

• Valor central — a frase de uma linha da seção Core Value do PROJECT.md.
• Foco atual — qual fase está ativa.

Posição Atual

Onde o projeto está agora:

Campo	Formato
Phase:	X of Y (Phase name)
Plan:	A of B in current phase
Status:	Texto livre, ex.: Ready to execute, Executing Phase 4, Phase complete — ready for verification
Last activity:	Data ISO (YYYY-MM-DD) quando escrito por handler; prosa narrativa quando elaborado pelo executor
Progress:	Barra visual, ex.: [████░░░░░░] 40%

Todos os campos nesta seção têm valor único, e a seção é sobrescrita em vez de receber conteúdo anexado. Uma segunda linha Phase: não representa uma segunda posição nem um histórico — é uma entrada malformada. Os leitores não resolvem uma duplicata pela ordem no documento; eles a resolvem pela forma, verificada nesta ordem independentemente de onde cada forma apareça dentro da seção ## Current Position — negrito **Phase:** value em qualquer ponto da seção, depois texto simples Phase: value no início de uma linha, depois uma linha de tabela | Phase | value | — e apenas dentro da forma vencedora prevalece a primeira ocorrência. Uma linha em negrito ou em texto simples fora desta seção — uma entrada anterior em ## Archive, ou uma linha em negrito no frontmatter YAML — nunca é consultada; a implementação em produção sempre restringe o escopo à seção ## Current Position primeiro (#2956) antes de aplicar a hierarquia de formas. Duas consequências práticas: uma duplicata escrita em uma forma de prioridade mais alta vence mesmo que apareça por último na seção, de modo que uma linha em negrito acrescentada "para dar ênfase" sobrescreve silenciosamente uma linha em texto simples anterior em vez de ser ignorada; e uma linha Phase: indentada é invisível para a forma em texto simples (que se ancora no início da linha) e recai sobre a próxima forma que corresponder. A regra "a forma de prioridade mais alta vence" tem duas arestas afiadas: uma linha em negrito cujo valor é apenas espaço em branco final é resolvida como uma string vazia, em vez de recair sobre uma linha em texto simples válida abaixo dela; e uma linha de tabela cuja célula de rótulo está ela mesma em negrito (| **Phase:** | value |) é capturada primeiro pelo padrão em negrito, retornando o texto literal da célula, incluindo suas barras verticais. Escreva a seção substituindo-a, nunca adicionando uma linha.

O histórico de progresso não pertence aqui. Ele se acumula em ### Performance Metrics logo abaixo, que é a seção projetada para crescer.

Os campos Status: e Last activity: nesta seção são atualizados pelos handlers do MSD quando o valor existente é um padrão de template conhecido (invariante de Knuth: valores elaborados pelo executor são preservados). A lista completa de padrões de handler conhecidos está em KNOWN_TEMPLATE_DEFAULTS dentro de msd-core/bin/lib/state-document.cjs.

Métricas de Desempenho

Rastreamento de velocidade de execução:

• Total de planos concluídos, duração média por plano.
• Tabela de detalhamento por fase (Phase | Plans | Total | Avg/Plan).
• Tendência recente: Improving / Stable / Degrading.

Atualizado após cada conclusão de plano.

Contexto Acumulado

Decisões — um resumo das decisões recentes que afetam o trabalho atual (o log completo vive em PROJECT.md). Adicionado via msd-tools state add-decision.

Todos Pendentes — contagem e referência a .planning/todos/pending/. Capturado via /msd-capture.

Bloqueadores/Preocupações — problemas que afetam trabalhos futuros, prefixados com a fase de origem. Adicionado via msd-tools state add-blocker; resolvido via msd-tools state resolve-blocker.

Continuidade de Sessão

Permite retomada instantânea de sessão:

• Last session: — timestamp ISO-8601 da última sessão.
• Stopped at: — descrição da última ação concluída.
• Resume file: — caminho para um arquivo .continue-here*.md se existir, caso contrário None.

---

Compatibilidade retroativa

Os campos de ciclo de vida de fase (active_phase, next_action, next_phases e progress.percent para a barra) são aditivos e opt-in por projeto:

• Um STATE.md sem nenhum dos campos de ciclo de vida populados é renderizado byte a byte de forma idêntica à v1.38.x e anteriores.
• Adicionar qualquer campo de ciclo de vida é opt-in — o renderizador degrada graciosamente quando os campos estão ausentes.
• A barra de progresso é opt-in mesmo quando o bloco progress existe: somente progress.percent ativa a barra; total_phases e completed_phases sozinhos não ativam.

O conjunto de testes formatMsdState #2833 backward compatibility em tests/msd-statusline.test.cjs garante essa promessa; qualquer mudança que quebre a renderização legada do STATE.md fará o conjunto falhar.

---

Relacionados

• Artefatos de planejamento
• Configuração
• O ciclo de fases
• índice da documentação