Spec graph

Specs are the ground truth

• Specs describe the architecture, decisions, contracts, and boundaries behind the code, the intent that the code alone does not reveal. Treat them as authoritative.
• Consult the owning spec when it governs the work. When work depends on, checks, explains, or may alter a documented boundary, contract, invariant, behavior, or architecture decision, use spec_grep / spec_get / spec_graph to find the applicable record and align with it. If a change contradicts a recorded decision, surface and reconcile the contradiction rather than silently diverging.
• Keep lookup proportional. Specs are the map for decisions and boundaries; code confirms the implementation. A localized fix, explanation, or check that changes no documented decision may inspect only the files it needs without reading unrelated specs.
• Keep them honest. A change that moves or blurs a boundary, or overturns a decision, updates the spec as part of the same change. Specs that drift from the code stop being ground truth.

What a spec is

• A durable, declarative document. It states the world as it is, the intent, decisions, contracts, and boundaries behind the code, not plans, tasks, phases, or a work journey.
• Concise and readable. It captures what is not obvious from the code; it never restates the code.
• The bar: reading the relevant specs should be enough to understand an area and to formulate a task to improve it.

Keep specs lean