Repository navigation
docs: reconcile OpenSpec, product docs, and the DOX chain with shipped code - #8
Merged
Merged
Conversation
…d code The repo had three independent kinds of documentation drift, found by auditing every change, spec, AGENTS.md, and product doc against the code on main. The worst was not omission — it was documentation that actively contradicted the app. OpenSpec: 22 changes were fully implemented and merged but never archived, so openspec/specs/ — the source of truth after archive — described 11 capabilities while ~18 live ones existed only as drafts under openspec/changes/*/specs/. Archived them in three batches (usage, workers, UI/chat/sync), validating --strict per change; specs went 11 -> 30 and only two changes remain open, both legitimately: repair-native-runtime-integrity (16/20, phase 1 still diagnosing RefCell reentrancy) and unlock-chat-checkout-switching (0/9, the checkout lock is still in crates/ui/src/pickers.rs:1253). The canonical spec for omp-live-voice was the dangerous one: it carried `Purpose: TBD` and forbade Live Voice during active runs, while the shipped code allows it in `Working` and `AwaitingInput` (crates/engine/src/sessions.rs, crates/harness/src/omp/live_voice.rs). Anyone implementing against that spec would have coded the opposite of the product. Archiving allow-live-voice-during-active-run and fix-live-voice-delegation-continuity replaced it with the real contract. elevate-workers-wait-ceiling-and-bridge-timeout proposed a 120s wait ceiling that orchestrator-owns-workers-wait had already replaced with 4h. It was archived only after the change that supersedes it, so specs/workers-host-bridge now states WAIT_FOR_STATUS_MAX_TIMEOUT_SECONDS = 14400, not the dead 120s. Two tasks.md files (add-agy-worker-runtime, polish-workers-subagent-widget) had every box unchecked against shipped, tested code; boxes were ticked from verified evidence only. Product docs: FUNCTIONAL-BASELINE.html still listed "TUI ratatui" as an active feature and viewport, including in the Mermaid diagrams, for a crate that was deleted; it now inventories 21 areas (3 OK, 18 PARCIAL) and covers Workers, Live Voice, Chat Transcript Export, Projects Settings, Dev Inspector, and Managed Provider Usage. New rows are PARCIAL, not OK, because the file defines OK as runtime evidence in-session and these have none yet. ARCHITECTURE.md was missing 4 of the 12 workspace members (comet-syntax, zeron-theme, zeron-update, zeron-workers-unpeel) and the whole Trajectory surface. ARCHITECTURE.md and docs/PARITY.md both claimed mobile was out of scope while apps/ios/ ships a SwiftUI client with its own XCTest suite; PARITY also omitted the OpenCode and OMP harness adapters and marked Token Usage as dropped and the Idle Reaper as deferred, both of which shipped. CONTEXT.md is the naming authority the root AGENTS.md makes mandatory reading, and it lacked the terms the code uses daily: Worker/CLI Worker, Live Voice, Degraded Interval, Raw Reveal. Each entry now states what the term is NOT, like the existing Chat/Session and Managed Provider Usage entries — that pairing is what keeps the collisions from coming back. DOX chain: three AGENTS.md pointed verification at crates/sync/tests/edge_convergence.rs, renamed to registry_edge.rs, so the documented proof command did not run. apps/AGENTS.md claimed the iOS client had no test suite (six XCTest files exist). crates/ui/AGENTS.md had five Settings contracts stranded after the Child DOX Index, breaking the section contract, and omitted the workers/ subtree it governs. Docs only: no source file changed. openspec validate --specs --strict passes 30/30 and --changes --strict passes 2/2.
… and token-usage claims
|
Too many files changed for review (134 files, 100 file limit). Bypass the limit by tagging |
|
Important
This repository does not receive automatic reviews because it has fewer than 10 stars. ⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Team Run ID: Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Intent
docs: reconcile OpenSpec, product docs, and the DOX chain with shipped code
The repo had three independent kinds of documentation drift, found by
auditing every change, spec, AGENTS.md, and product doc against the code on
main. The worst was not omission — it was documentation that actively
contradicted the app.
OpenSpec: 22 changes were fully implemented and merged but never archived,
so openspec/specs/ — the source of truth after archive — described 11
capabilities while ~18 live ones existed only as drafts under
openspec/changes/*/specs/. Archived them in three batches (usage, workers,
UI/chat/sync), validating --strict per change; specs went 11 -> 30 and only
two changes remain open, both legitimately: repair-native-runtime-integrity
(16/20, phase 1 still diagnosing RefCell reentrancy) and
unlock-chat-checkout-switching (0/9, the checkout lock is still in
crates/ui/src/pickers.rs:1253).
The canonical spec for omp-live-voice was the dangerous one: it carried
Purpose: TBDand forbade Live Voice during active runs, while the shippedcode allows it in
WorkingandAwaitingInput(crates/engine/src/sessions.rs, crates/harness/src/omp/live_voice.rs).
Anyone implementing against that spec would have coded the opposite of the
product. Archiving allow-live-voice-during-active-run and
fix-live-voice-delegation-continuity replaced it with the real contract.
elevate-workers-wait-ceiling-and-bridge-timeout proposed a 120s wait ceiling
that orchestrator-owns-workers-wait had already replaced with 4h. It was
archived only after the change that supersedes it, so
specs/workers-host-bridge now states WAIT_FOR_STATUS_MAX_TIMEOUT_SECONDS =
14400, not the dead 120s. Two tasks.md files (add-agy-worker-runtime,
polish-workers-subagent-widget) had every box unchecked against shipped,
tested code; boxes were ticked from verified evidence only.
Product docs: FUNCTIONAL-BASELINE.html still listed "TUI ratatui" as an
active feature and viewport, including in the Mermaid diagrams, for a crate
that was deleted; it now inventories 21 areas (3 OK, 18 PARCIAL) and covers
Workers, Live Voice, Chat Transcript Export, Projects Settings, Dev
Inspector, and Managed Provider Usage. New rows are PARCIAL, not OK, because
the file defines OK as runtime evidence in-session and these have none yet.
ARCHITECTURE.md was missing 4 of the 12 workspace members (comet-syntax,
zeron-theme, zeron-update, zeron-workers-unpeel) and the whole Trajectory
surface. ARCHITECTURE.md and docs/PARITY.md both claimed mobile was out of
scope while apps/ios/ ships a SwiftUI client with its own XCTest suite;
PARITY also omitted the OpenCode and OMP harness adapters and marked Token
Usage as dropped and the Idle Reaper as deferred, both of which shipped.
CONTEXT.md is the naming authority the root AGENTS.md makes mandatory
reading, and it lacked the terms the code uses daily: Worker/CLI Worker,
Live Voice, Degraded Interval, Raw Reveal. Each entry now states what the
term is NOT, like the existing Chat/Session and Managed Provider Usage
entries — that pairing is what keeps the collisions from coming back.
DOX chain: three AGENTS.md pointed verification at
crates/sync/tests/edge_convergence.rs, renamed to registry_edge.rs, so the
documented proof command did not run. apps/AGENTS.md claimed the iOS client
had no test suite (six XCTest files exist). crates/ui/AGENTS.md had five
Settings contracts stranded after the Child DOX Index, breaking the section
contract, and omitted the workers/ subtree it governs.
Docs only: no source file changed. openspec validate --specs --strict passes
30/30 and --changes --strict passes 2/2.
Contexto adicional de decisão (o intent acima é o registro da mudança): a auditoria que originou isto foi read-only e cruzou branches (só existe main), os 25 changes OpenSpec abertos, os 11 specs, os 21 AGENTS.md e as docs de produto contra o código. Decisões deliberadas: (1) arquivei orchestrator-owns-workers-wait ANTES do change superado elevate-workers-wait-ceiling-and-bridge-timeout, de propósito, para o spec final de workers-host-bridge dizer 14400s e não os 120s mortos; (2) as features que adicionei ao FUNCTIONAL-BASELINE.html entraram como PARCIAL e não OK porque a convenção declarada no próprio arquivo é que OK exige evidência de runtime na sessão; (3) deixei repair-native-runtime-integrity e unlock-chat-checkout-switching abertos porque são trabalho real que falta e arquivar seria mentir. Nenhum arquivo de código foi tocado, por isso não rodei cargo test; verificação foi openspec validate --specs --strict 30/30 e --changes --strict 2/2. O working tree do checkout principal tem trabalho não commitado do usuário em third_party/ (sync do unpeel) que NÃO faz parte desta mudança e por isso esta validação roda numa worktree limpa.
What Changed
openspec/changes/archive/2026-09-03-*, promoting their delta specs intoopenspec/specs/(11 → 30 canonical specs).omp-live-voicenow states that Live Voice is allowed duringWorking/AwaitingInputruns,workers-host-bridgecarries the 14400s wait ceiling instead of the superseded 120s, andtasks.mdboxes foradd-agy-worker-runtimeandpolish-workers-subagent-widgetwere ticked against shipped code. Onlyrepair-native-runtime-integrityandunlock-chat-checkout-switchingremain open.FUNCTIONAL-BASELINE.htmldrops the deleted ratatui TUI and inventories 21 areas (Workers, Live Voice, Chat Transcript Export, Projects Settings, Dev Inspector, Managed Provider Usage added as PARCIAL);ARCHITECTURE.mdlists all 12 workspace members and the Trajectory surface;docs/PARITY.mdadds the iOS client, OpenCode/OMP adapters, and marks Token Usage and Idle Reaper as shipped;CONTEXT.mdgains Worker/CLI Worker, Live Voice, Degraded Interval, and Raw Reveal entries;fork_changelog.mdandREADME.zh-CN.mdrefreshed.apps/,crates/doc/,crates/sync/,edge/AGENTS.md,openspec/project.md, and the doc comment incrates/engine/tests/workspace_sync.rsnow point atcrates/sync/tests/registry_edge.rs(renamed fromedge_convergence.rs);apps/AGENTS.mddocuments the iOS XCTest suite;crates/ui/AGENTS.mdmoves the stranded Settings contracts above the Child DOX Index and adds theworkers/subtree.Risk Assessment
✅ Low: Mudança docs-only cujos fix rounds foram verificados contra o código e contra o CLI: openspec/changes/ agora rastreia só os dois changes legítimos (git ls-files confirma o move), openspec validate dá 30/30 specs e 2/2 changes, a contagem do resumo (48 done + 1 changed shape = 49, 5 partial) bate com as tabelas, e as referências de código citadas (SESSION_IDLE em sessions.rs, update_provider_telemetry em activity_bridge.rs:510, view.rs:1455/1607, instance_lock.rs) existem onde o texto diz.
Testing
Confirmei que o diff é docs-only, rodei openspec list/validate --strict (2/2 changes, 30/30 specs) com transcript salvo, cruzei cada alegação do intent contra o código e os docs (ceiling 14400s, Live Voice em Working/AwaitingInput, stall watchdog, token usage refs, contagem 49/5 do PARITY, membros do workspace, termos do CONTEXT, XCTest do iOS), executei o comando de prova documentado na cadeia DOX para o zeron-sync (compila e roda, testes ignored por exigirem edge vivo, como o AGENTS.md declara) e renderizei o FUNCTIONAL-BASELINE.html no Chrome headless, capturando screenshot que mostra 21 áreas (3 OK, 18 PARCIAL) e o diagrama sem TUI; tudo bate com o intent e a árvore ficou limpa.
~/.no-mistakes/evidence/01M1JYT9CZSE7HBBHTF055FR93/functional-baseline-render.png)Evidence: openspec list/validate --strict transcript
$ ls openspec/changes archive repair-native-runtime-integrity unlock-chat-checkout-switching $ openspec validate --changes --strict ✓ change/repair-native-runtime-integrity ✓ change/unlock-chat-checkout-switching Totals: 2 passed, 0 failed (2 items) $ openspec validate --specs --strict Totals: 30 passed, 0 failed (30 items)Evidence: Checagem das alegações do intent contra código e docs
Evidence: Comando de prova documentado na cadeia DOX (crates/sync)
Pipeline
Updates from git push no-mistakes
✅ **intent** - passed
✅ No issues found.
✅ **Rebase** - passed
✅ No issues found.
openspec/changes/add-agy-worker-runtime/tasks.md:13- O intent exige que "only two changes remain open" e queopenspec validate --changes --strictpasse 2/2, mas o commit 96d50dd ainda rastreia os 23 diretórios originais emopenspec/changes/(git ls-tree confirma; só dois arquivos foram deletados:fix-dead-antigravity-error-and-workers-timeout/specs/antigravity-managed-usage/spec.mdepolish-workers-subagent-widget/tasks.md). O archive foi commitado como cópia, não como move — as deleções ficaram fora do commit. Efeito observável:openspec list --changesmostra 25 changes;openspec validate --changes --strictdá 23 passed / 2 failed (elevate-workers-wait-ceiling-and-bridge-timeout e fix-live-voice-delegation-continuity falham porque os deltas MODIFIED agora colidem com o spec canônico já atualizado);polish-workers-subagent-widgetfica aberto com "No tasks"; e as cópias abertas são versões PRÉ-edição (add-agy-worker-runtime aberto está 0/5, o arquivado 5/5; allow-live-voice aberto tem o header "Media and operational context remain transient" enquanto o canônico usa "Media remains inside OMP"). Umopenspec archivefuturo tentaria reaplicar os deltas em cima de specs que já os contêm. Contradiz diretamente o critério do intent; a remediação é mecânica (remover os 23 diretórios abertos — em todos os 14 casos que divergem, a versão arquivada é a mais nova e é a que foi aplicada ao spec canônico), mas por ser deleção em massa e contradição de intent, precisa de confirmação do autor.docs/PARITY.md:49- §3.2 passou paradoneafirmando "and stall watchdog", mascrates/engine/src/sessions.rs:15-17diz que o stall watchdog foi "deliberately NOT ported (rejected in review)". É exatamente o tipo de doc-que-contradiz-código que o intent diz querer eliminar. O idle reaper existe, mas no próprio sessions engine (SESSION_IDLEde 30 min,sessions.rs:~2508), não emhibernation_candidates/idle_since_unix_msdecrates/workers-unpeel, que é hibernação de Worker (outra capability, specworker-hibernation).ARCHITECTURE.md:237(linha reescrita neste diff) também mantém "10min stall watchdog". Correção: citar o reaper de 30 min do sessions engine como evidência e registrar o stall watchdog como decisão explícita de não portar (mantendo-o fora de "Engine hardening" na linha 107 só se o texto disser que foi rejeitado, não que foi feito).docs/PARITY.md:99- A linha reescreve "Token-usage display dropped" comodone, mas o item original é o display de token usage de Chat (WatchUsage, doctokens, profile heatmap), que continua ausente e foi dropado por decisão de spec; o que shipou é o Worker model/token usage do widget de Workers (specworkers-widget-model-usage). Além disso as duas referências de linha estão erradas:activity_bridge.rs:1400cai dentro de um teste (tempfile::tempdir()de fixture) edetails_sidebar/view.rs:1623é o contador de workflows/subagents/workers; a apresentação de tokens está emview.rs:1455/1607. Sugestão: manter o item de Chat como dropped e adicionar uma linha própria para Worker token usage com refs corretas — como isso muda a leitura de paridade do produto, precisa do autor.🔧 Fix: drop copied openspec changes; fix stall watchdog and token-usage claims
2 issues (1 warning, 1 info) still open:
docs/PARITY.md:113- O resumo diz "43 done · 6 partial", mas as tabelas acima têm 48 linhasdone(49 contando adone (changed shape)) e 5partial. O fix round só incrementou o done de 42 para 43 ao adicionar a linha de Worker token usage, mas esta mudança também flipou 3.2 de partial para done (6→5 partial) e adicionou as linhas OpenCode adapter e OMP adapter & Live Voice; além disso o número base já estava errado (42 vs 44 reais). É uma contagem que contradiz o próprio documento, o tipo de deriva que o intent existe para eliminar. Correção: reescrever como 48 done · 5 partial (ou 49 se contar a linha "changed shape"), contando pelas linhas das tabelas.docs/PARITY.md:108- A linha de "Engine hardening" (editada neste diff para remover idle reaper/stall watchdog) ainda listasingle-instance lockcomo deferido, enquanto a linha 3.1 do mesmo arquivo o marca como entregue ("single-instance data-dir lock") e o código existe emcrates/engine/src/instance_lock.rs(flock exclusivo em{data_dir}/engine.lock). Contradição pré-existente na base, mas está na mesma linha que a mudança reescreveu; a remoção do item da lista de deferidos é trivial e alinha com o objetivo declarado. Não bloqueia.🔧 Fix: recount PARITY summary rows; drop shipped lock from deferred
1 info still open:
docs/PARITY.md:12- A linha 1.1 Window shell ainda listasingle-instance lockcomo deferido, enquanto 3.1 (linha 48) o marca entregue ("single-instance data-dir lock"),crates/engine/src/instance_lock.rsexiste, e o fix round já removeu o mesmo item da lista de Engine hardening (linha 108). É a mesma contradição interna que a rodada anterior corrigiu, só que numa linha não tocada pelo diff. Remédio mínimo: retirarsingle-instance lockda lista de deferidos de 1.1. Não bloqueia.✅ **Test** - passed
✅ No issues found.
git diff --name-only c99834d8..08593d00filtrado por não-docs e third_party/ → vazio (docs-only confirmado)ls openspec/changeseopenspec list --changes→ só repair-native-runtime-integrity e unlock-chat-checkout-switchingopenspec validate --changes --strict→ 2 passed / 0 failedopenspec validate --specs --strict→ 30 passed / 0 failed;openspec list --specs→ 30grep deWAIT_FOR_STATUS_MAX_TIMEOUT_SECONDS/14400 em openspec/specs/workers-host-bridge/spec.md vscrates/workers-unpeel/src/controller_mcp.rs:23grep deTBD/Working/AwaitingInputem openspec/specs/omp-live-voice/spec.mdContagem de linhas de tabela por status em docs/PARITY.md (48 done + 1 done (changed shape) + 5 partial) vs resumo declaradoVerificação de docs/PARITY.md e ARCHITECTURE.md contracrates/engine/src/sessions.rs:12-18(stall watchdog não portado) e existência decrates/engine/src/instance_lock.rsConferência decrates/ui/src/details_sidebar/view.rs:1455e:1607como refs de apresentação de tokensgrep deedge_convergence|registry_edgeem todos os AGENTS.md +ls crates/sync/tests/(só registry_edge.rs referenciado, arquivo existe)cargo test -p zeron-sync --test registry_edge→ ok, 0 passed / 0 failed / 2 ignored (exigem ZERON_EDGE_WS, conforme documentado em crates/sync/AGENTS.md)find apps/ios -name '*Tests*.swift'→ 6 arquivos XCTest, batendo com apps/AGENTS.mdMembros do workspace em Cargo.toml vs menções em ARCHITECTURE.md (comet-syntax, zeron-theme, zeron-update, zeron-workers-unpeel, Trajectory)grep de termos Worker/CLI Worker, Live Voice, Degraded Interval, Raw Reveal em CONTEXT.mdRender headless do FUNCTIONAL-BASELINE.html no Chrome (screenshot 1280x6000) + contagem de células de status (3 OK / 18 PARCIAL) + grep de ratatui/TUI → 0git status --porcelainao final → árvore limpa, target/ ignorado🔧 **Document** - 1 issue found → auto-fixed ✅
crates/engine/tests/workspace_sync.rs:8- O doc comment//!em crates/engine/tests/workspace_sync.rs:8 ainda referencia o testeedge_convergencede zeron-sync, renomeado paracrates/sync/tests/registry_edge.rs. Não editei porque a decisão registrada nesta run fixa a mudança como docs-only (nenhum arquivo de código). Correção trivial de uma palavra num comentário, sem efeito de comportamento, para um commit à parte.🔧 Fix: point workspace_sync doc comment at registry_edge test
✅ Re-checked - no issues remain.
✅ **Lint** - passed
✅ No issues found.
✅ **Push** - passed
✅ No issues found.