Documentation standards and maintenance

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.

ork roadmap feat --thread <thread>
ork docs verificar
ork docs sincronizar

Separate 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.

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 and the KG3 index and queries arrived without changing the contract. KG3’s first query-cost measurement records bytes and latency for both arms, with no measured tokens; it is not the benchmark baseline and draws no conclusion about savings. Phase consumption remains out of scope.