Standards
Documentation standards and maintenance
Keep identity, behavior, evidence and planning in their proper places.
Document verifiable behavior
The PLAT → SYS → MOD → FEAT hierarchy organizes the product. Each page identifies purpose, state, sources and relationships. A feature describes preconditions, flow, alternatives, postconditions, rules and acceptance criteria. Data, APIs and operations need explicit limits. In Orkastery, a new FEAT number comes from ork roadmap feat, reserved across machines; never from the highest number on your branch. Architecture decisions live in numbered ADRs, with context, criteria, compared options and the decision; ADR-001 records where the network of a person’s machines lives.
ork roadmap feat --thread <thread>
ork docs verificar
ork docs sincronizarSeparate plans from availability
The roadmap records the problem, goal, scope, dependencies, decisions and validation criteria. Merged code, passing tests, deployment and user exposure are different facts. On these sites, the roadmap appears only as a monthly summary linked to its source.
Code state follows git both ways: codigo: Mesclado requires the merge commit on the base, and the ship(<thread>) merge of the item’s thread requires codigo: Mesclado. ork docs verificar fails on the mismatch (docs.paridade.merge) and on an index that does not match the frontmatter (docs.paridade.indice); on a PR, with --pr, both only warn, because the mismatch belongs to main. ork docs sincronizar --escrever, in a docs PR after the merge, fixes both.
In Orkastery, ork docs sincronizar updates code state from the ledger and git, and the sdlc section from the thread; it never changes lifecycle, documentation, deployment, exposure or enablement. In a thread’s worktree it touches only that thread’s item; --so selects items and --todos covers all of them. Closing a thread releases its item reservation or passes it to another open thread on the same item.
Editorial and visual review
Use sentence case for headings and labels; preserve acronyms, commands and proper names. Diagrams have titles, descriptions and a sequence readable without relying on color. Indexes and templates guide editing; brand assets remain at the source and do not represent additional features.
The public snapshot records relative paths and hashes. Synchronizing a changed source invalidates affected reviews. All three languages require explicit review, and builds use the versioned snapshot without fetching remote content.
A contract is not a measured result
KG1 defines separate graph and benchmark contracts. The graph preserves provenance and access restrictions and recomputes content-derived identities. The benchmark fixes A/B pairs, tasks, controls, attempts and measurement sources. A synthetic corpus validates the contract; it demonstrates neither token savings, latency nor significance. Missing measurements remain null with a reason. KG2 extraction, the KG3 index and queries and the KG4 incremental index, with the same bytes as a full extraction, arrived without changing the contract. KG4 also measured the deterministic part and fixed the paid-run protocol as not-run; the paid run is still pending, and no published number is a measured saving. The KG3 analyzers, typescript and micromark, became package dependencies with exact versions, without changing the ork.ts-ast and ork.md-structure labels. In version 0.6.10, KG3 node queries also return the sha256 and Git blob of each cited source, which the KG1 contract already puts in every piece of evidence, and, for each edge, whether its sources match the tree, without changing the contract.