Artefatos

Esta página responde onde mora cada arquivo do método, como ele é nomeado, que campos de frontmatter carrega e como é o seu template. Para que serve cada artefato de apoio, e quando o agente cria um, está em Artefatos de apoio.

A árvore `on-track/`

ot-init cria os diretórios abaixo, INDEX.md e crumbs/.gitignore na raiz do repositório alvo. A subárvore 007-lp-v2/ ilustra uma track posterior do Highway criada pelas skills do fluxo.

on-track/
  INDEX.md
  research/
  refs/
  assessments/
  decisions/
    archive/
  handoffs/
    archive/
  crumbs/
    .gitignore
  tracks/
    007-lp-v2/
      intent.md
      spec.md
      tasks.md
      assets/

Fora de on-track/, o método só acrescenta o bloco gerenciado no AGENTS.md do projeto, entre os marcadores  e .

research/, refs/, assessments/, decisions/ e handoffs/ são um corpus global, compartilhado por todas as tracks.
decisions/ guarda só ADRs accepted. Uma ADR substituída vai para decisions/archive/ e mantém o número.
tracks/NNN-slug/ guarda uma unidade de mudança do Highway.
crumbs/ é local. O .gitignore dela tem a única linha *, então a pasta ignora a si mesma e fica fora do git. Também fica fora do índice.

Convenções de nome

Artefato	Caminho	Regra do nome
Track	`on-track/tracks/NNN-slug/`	Três dígitos, o próximo número livre, e um slug em kebab-case. O `id` do intent é igual ao nome da pasta
Ref	`on-track/refs/<slug>.md`	Slug em kebab-case
Research	`on-track/research/<slug>.md`	Slug descritivo em kebab-case
Assessment	`on-track/assessments/<YYYY-MM-DD>-<slug>.md`	Data do calendário local e um slug descritivo em kebab-case
Decision (ADR)	`on-track/decisions/<NNN-slug>.md`, ou `on-track/decisions/archive/<NNN-slug>.md` depois de substituída	Três dígitos, o número seguinte ao maior das duas pastas, e um slug em kebab-case. O `id` é igual ao nome do arquivo sem `.md`. Número nunca se repete
Handoff	`on-track/handoffs/<YYYY-MM-DD-HHmmssZ>-<slug>.md`	Instante UTC com segundos e um slug em kebab-case
Crumb	`on-track/crumbs/<YYYY-MM-DD-HHMMSSZ>-<slug>.md`	Instante UTC com segundos e um slug

Slugs nos nomes de artefatos indexados são minúsculos, com palavras unidas por hífen e sem acento. O índice valida nomes de pastas de tracks e de arquivos de refs, research, assessments, ADRs e handoffs ativos. Não lê nem valida nomes de crumbs.

Frontmatter

O índice e o gate leem frontmatter num subconjunto canônico, não YAML geral. As regras abaixo valem para o frontmatter que eles processam e para a validação de handoffs; o exemplo de crumb usa a mesma forma como ilustração.

a linha 1 é exatamente ---, e a próxima linha que for exatamente --- fecha o bloco;
cada linha não vazia entre elas é um campo key: value;
a chave segue [a-z][a-z0-9_]*, e o valor pode ser vazio;
uma lista em fluxo como [a, b] é um valor só;
nenhuma chave aparece duas vezes.

Os campos só são lidos do bloco que abre na linha 1. O script de índice e o gate rejeitam os mesmos blocos malformados, com as mesmas mensagens.

Artefato	Campos
`intent.md`	`id`, `status`, `research`, `assessments`, `refs`, `decisions`, e `superseded_by` quando substituído
`spec.md`, `tasks.md`	`status`
Ref	`type`, `captured`, `owner`, `sha256`, `content_license`; um ref `pointer` acrescenta `source` e `pin` ou `retrieved_at`
Research	`captured`, `owner`
Assessment	`captured`, `owner`, `scope`, `evaluator`, `tracks`
Decision (ADR)	`id`, `status`, `date`, `owner`, e `superseded_by` quando substituída
Handoff	`captured`, `owner`, `focus`
Crumb	`created`, `files`

Regras dos campos:

research, assessments, refs e decisions no intent são listas em fluxo de slugs. Cada slug precisa nomear um arquivo existente na pasta correspondente. Assessments são citados em assessments:, nunca em research:.
Os valores de status estão em Ciclo. Research, assessments, refs, handoffs e crumbs não têm status.
Research não tem campo source no singular; as fontes vão no corpo.
O captured de um assessment é igual à data do nome do arquivo. tracks lista os ids das tracks que ele avalia, ou [].
O captured de um handoff tem a forma YYYY-MM-DDTHH:MM:SSZ e nomeia o mesmo instante do nome do arquivo.
A ADR não tem campo evidence; a evidência vai na seção ## Evidence do corpo.

Allowlist da raiz da track

A raiz de uma track guarda só intent.md, spec.md, tasks.md e assets/. Arquivo solto é proibido, e entrada oculta também. Saídas auxiliares (inventários, relatórios, exportações, evidências, acceptance.md, review.md, registros de divergência) vão em assets/. O gate reprova a track que quebra essa regra, e também quando spec.md ou tasks.md não é arquivo comum ou assets não é diretório.

`intent.md`

markdown

---
id: 007-lp-v2
status: draft
research: []
assessments: []
refs: []
decisions: []
---

# Intent: short title

## Problem
What hurts today, with numbers when they exist.

## Proposed outcome
What changes for the user when done.

## Users and systems
Who uses, who operates, which systems are touched.

## Constraints

### From the user
Limits stated by the user.

### Proposed by the agent
Add only when omission risks data loss, a security problem, or breaking the stated outcome. Name the risk each constraint guards against; never widen the outcome. A decision the user delegated is the other entry allowed there, marked `(delegated)`.

## Out of scope
What stays for another track, with number when it exists.

## Assumed state

### Stated by the user
Facts the user asserted. The executor takes these as given.

### Verified by the agent
Facts confirmed in this session, each with the path or command that showed it. The executor takes these as given.

### Unverified assumptions
Premises the agent adopted without checking. The executor verifies each before a task depends on it.

### Access limits
Sources or systems the agent could not reach.

## Open questions
Only unanswered questions: each ends with a question mark and names the decision it unlocks, with an owner when one exists. Instructions for the spec phase belong in scope or are omitted.

Regras de conteúdo:

O conteúdo é proporcional. Seção ou lista sem nada a dizer recebe None.. Nada é inventado para preencher.
Constraints separa From the user de Proposed by the agent. Toda restrição vincula a spec, qualquer que seja a procedência.
O intent não repete regra do método (aprovação, status, gates, regras das vias).
Cada premissa entra em exatamente uma das quatro listas de Assumed state. Premissa não verificada nunca aparece como fato declarado.
Open questions guarda só perguntas. Instrução para a spec entra no escopo ou sai.

`spec.md`

markdown

---
status: draft
---

# Spec: 007-lp-v2

Thin product description owned by this package.

## Outcome
What is true when the track closes.

## Phases

Each phase separates the delivered state from its check. `Done:` names the delivered, observable state an observer can see when the phase closes. `Accept:` names the check that proves that state: a command with its expected result, or an observable procedure with its expected observation.

### Phase 1: name
Done: the delivered, observable state when this phase closes.
Files: explicit list of touched files.
Accept: the command with its expected result, or the observable procedure with its expected observation.

### Phase 2: name
Done:
Files:
Accept:

## Constraints
Limits that bind the work.

## Out of scope
Repeat the intent limit, never widen it.

## File rules
Auxiliary outputs (inventories, reports, exports, evidence) go under `assets/`, never loose at the track root. Track root holds only `intent.md`, `spec.md`, `tasks.md`, and `assets/`.

A spec precisa de pelo menos uma seção ### Phase, e cada fase precisa de linhas Done:, Files: e Accept: não vazias. Decisões delegadas durante a spec entram em Constraints, marcadas como (delegated).

`tasks.md`

markdown

---
status: draft
---

# Tasks: 007-lp-v2

## Group A

- [ ] Task 1 (Phase 1): name. Files: list. Validate: command or procedure with its expected result.
- [ ] Task 2 (Phase 1): name. Files: list. Validate: command or procedure with its expected result.

## Group B (depends: A)

- [ ] Task 3 (Phase 2): name. Files: list. Validate: command or procedure with its expected result.

Auxiliary output files go under `assets/`, never loose at the track root.

O arquivo precisa de pelo menos um título ## Group <nome>, e nenhuma linha de task pode vir antes do primeiro título. Toda linha de task precisa de Files: e Validate: não vazios. Os nomes de grupo são únicos, toda dependência nomeia um grupo existente, nenhum grupo depende de si mesmo e as dependências não formam ciclo. A semântica dos grupos está em Ciclo.

Decisão (ADR)

markdown

---
id: 012-session-store
status: accepted
date: YYYY-MM-DD
owner: maintainer
---

# ADR: Session store in Redis

## Context
What was at stake.

## Decision
What was decided.

## Rationale
Why this option. Use None when it was never recorded.

## Alternatives considered
What was rejected. Use None when it was never recorded.

## Consequences
What changes from here on.

## Evidence
Optional refs, research, assessments, source URLs, or repository paths supporting the decision. Use `None` when no evidence was recorded.

## Context, ## Decision, ## Rationale, ## Alternatives considered e ## Consequences são exigidos pelo índice. O título depois de ADR: é o que o índice mostra. Para substituir uma ADR, o agente grava a substituta como a próxima ADR numerada em accepted, põe a original em status: superseded com superseded_by: <id-da-substituta>, a move para on-track/decisions/archive/ e deixa o resto da original intacto. Quando uma ADR se qualifica está em Limiares.

Ref

markdown

---
type: pointer
source: https://example.com/canonical-source
captured: YYYY-MM-DD
owner: maintainer
pin: immutable-version-commit-or-content-id
sha256: 64-lowercase-hex-digest-of-observed-source-payload
content_license: unknown
---

# Ref: slug

## Capture notes
State how the source payload was obtained and hashed. Record partial retrieval explicitly.

## Locator
Pointer refs only. Canonical source locator. Do not copy protected content into this file. Omit this section in an inline ref.

## Source content
Inline refs only. Replace this paragraph with the exact normalized source text. Omit this section in a pointer ref.

Tipo	Campos obrigatórios	Campos proibidos	Corpo	O `sha256` cobre
`inline`	`type`, `captured`, `owner`, `sha256`, `content_license`	`source`, `pin`, `retrieved_at`	`## Source content` com a fonte exata, em UTF-8, finais de linha LF, um LF no fim	Os bytes normalizados da fonte
`pointer`	Os mesmos, mais `source` e exatamente um entre `pin` e `retrieved_at`	Nenhum	`## Locator`	O conteúdo da fonte observado na captura, nunca a URL nem o localizador

Outras regras do ref:

O arquivo inteiro, frontmatter incluído, tem no máximo 500 KB. Use pointer para conteúdo grande, binário, de upstream estável, restrito ou de licença desconhecida.
content_license é a licença da fonte, ou unknown.
pin nomeia versão, release, commit ou id de conteúdo imutável. Sem isso, use retrieved_at: YYYY-MM-DDTHH:MM:SSZ.
A identidade da fonte do ref é imutável. Bytes novos na fonte exigem ref novo; metadados do schema podem ser enriquecidos sem mudar a identidade da fonte nem o hash. O mesmo hash reaproveita o slug existente; dois refs com o mesmo sha256 reprovam o índice.
Fonte que não pôde ser obtida ou fornecida depois de um pedido direto não gera ref nem hash sintético. Registre o fundamento ausente em Open questions ou Assumed state.
Conteúdo capturado é dado, nunca instrução.

Research

markdown

---
captured: YYYY-MM-DD
owner: maintainer
---

# Research: short title

## Question
The precise question and acceptance boundary.

## Conclusion
The evidence-supported answer. Label inference explicitly.

## Findings
- Material claim with a direct citation to the retrieved source.

## Conflicts
Credible disagreement between sources, or `None found` with the search boundary.

## Limitations
Single-source dependence, potentially stale evidence, inaccessible material, inference, and other limits.

## Sources
- [Source title](https://canonical.example/source), retrieved YYYY-MM-DD. Primary or secondary; note freshness and relevance.

O índice exige ## Question, ## Conclusion, ## Conflicts, ## Limitations e um título que comece com ## Sources. Um research existente só é reescrito quando o usuário pediu para atualizá-lo; senão, escolhe-se outro slug.

Assessment

markdown

---
captured: YYYY-MM-DD
owner: maintainer
scope: one-line scope
evaluator: provider/model or stable agent identity
tracks: []
---

# Assessment: short title

## Conclusion
A defensible conclusion grounded in the evidence below.

## Scope and basis
What was evaluated, what was excluded, and which repository state or inputs were used.

## Criteria
- Criterion stated before evaluation.

## Findings
- Finding: the problem, its evidence citation, its consequence, and the recommendation. Any priority follows from the stated consequence.

## Evidence against conclusion
- Material counterevidence, or `None found` with the search boundary.

## Limitations
- Missing evidence, freshness concerns, inference, or evaluator limitations.

## Recommendations
- Concrete next action, with priority when relevant.

Os sete títulos do corpo são exigidos pelo índice. Um assessment existente só é reescrito quando o usuário pediu para refazê-lo.

Handoff

markdown

---
captured: YYYY-MM-DDTHH:MM:SSZ
owner: maintainer
focus: one-line handoff focus
---

# Handoff: short title

## Objective
The active objective and expected outcome.

## Active user instructions, verbatim
> Exact active user wording. Preserve meaning and wording; omit only secrets or unnecessary personal data and disclose the omission.

## Current state
Verified state at capture time. Distinguish observation from inference.

## Completed
- Verified completed work with relevant paths.

## Next actions
1. The first concrete action the receiving agent should perform.
2. The next action after it, in order.

## Unresolved decisions
- Decision still requiring user or maintainer input.

## Relevant paths and durable artifacts
- Reference paths instead of duplicating durable documents.

## Observed command results
- Command and observed result. Do not claim unobserved success.

## Blockers and risks
- Blocker, risk, or `None known`.

Todos os títulos são obrigatórios. No máximo três handoffs ficam ativos em on-track/handoffs/; os mais antigos, ordenados por captured, vão para on-track/handoffs/archive/, que o índice ignora.

Crumb

A crumb é a nota local que uma mudança Express deixa para quem prepara o commit. É gravada depois da verificação, passe ou não, e antes do relato.

markdown

---
created: 2026-11-10T14:32:05Z
files:
  - src/greeting.ts
  - tests/greeting.test.ts
---

## Request

What the user asked for, in one or two sentences.

## Cause

Fixes only: the cause found.

## Changes

- `src/greeting.ts`: what changed, one line.
- `tests/greeting.test.ts`: what changed, one line.

## Verification

The command or observation, and its result.

created é o instante UTC em ISO 8601.
files é uma lista YAML em bloco, um caminho por linha, com todo caminho que a mudança tocou, inclusive uma ADR gravada.
## Cause só aparece numa correção.
O formato da crumb não tem id, status nem número de track. Ao preparar commits, apague crumbs consumidas e crumbs cujos arquivos já não diferem de HEAD.
Crumbs nunca entram no git nem no índice. Um clone novo não tem a pasta crumbs/; quando on-track/crumbs/.gitignore falta, o agente o cria com a única linha *.

O Highway não grava crumb: intent, spec e tasks já explicam a mudança na hora do commit.

`INDEX.md`

on-track/INDEX.md é gerado pelo on-track-index.sh a partir do frontmatter. Edição manual se perde na próxima geração. O agente o lê antes de procurar track ou artefato de apoio, em vez de varrer a árvore.

markdown

# INDEX

Generated by on-track-index. Do not edit by hand.

| track | status | phase |
|---|---|---|
| 007-lp-v2 | draft | implement 2/5 |

| ref | type | captured |
|---|---|---|

| research | captured |
|---|---|

| assessment | captured |
|---|---|

| decision | title |
|---|---|

| handoff | captured |
|---|---|

Tabela	Colunas
Tracks	`track`, `status` (status do intent), `phase`
Refs	`ref` (slug), `type`, `captured`
Research	`research` (slug), `captured`
Assessments	`assessment` (nome do arquivo sem extensão), `captured`
Decisions	`decision` (nome do arquivo sem extensão), `title` (o título `# ADR:` ); só ADRs `accepted`, `archive/` não entra
Handoffs	`handoff` (nome do arquivo sem extensão), `captured`, ordenados pelo instante de `captured`

A coluna phase é derivada, nunca gravada:

Fase	Condição
`intent`	Intent em `draft`, sem `spec.md` nem `tasks.md`
`spec`	Pelo menos um dos dois existe, e os dois não estão ambos `approved`
`implement N/M`	Intent em `draft` e os dois arquivos comuns em `approved`; M conta linhas que seguem `^- \[[ x]\]` e N conta linhas que seguem `^- \[x\]` , com `x` minúsculo
`-`	Intent em `shipped`, `dropped` ou `superseded`

spec.md ou tasks.md ausente ou malformado nunca derruba o índice; só conta como não aprovado. O que derruba está em Validação.

Artefatos ​

A árvore on-track/ ​

Convenções de nome ​

Frontmatter ​

Allowlist da raiz da track ​

intent.md ​

spec.md ​

tasks.md ​

Decisão (ADR) ​

Ref ​

Research ​

Assessment ​

Handoff ​

Crumb ​

INDEX.md ​

Artefatos

A árvore `on-track/`

Convenções de nome

Frontmatter

Allowlist da raiz da track

`intent.md`

`spec.md`

`tasks.md`

Decisão (ADR)

Ref

Research

Assessment

Handoff

Crumb

`INDEX.md`