Specification governance
This document governs ownership, synchronization, and change across goals, concepts, requirements, design, source, tests, artifacts, and observations.
Truth and ownership
TJ-GOV-01. Normative intent and observed reality are distinct. Goals and accepted requirements define what should happen. A deployed artifact in a particular environment, state, and interaction defines what did happen. A disagreement requires classification; neither side silently replaces the other.
TJ-GOV-02. Every fact has one authoritative owner for its domain. Generated views, summaries, tests, code, artifacts, and evidence may project or realize that fact but never acquire independent normative authority through duplication.
The ownership domains are:
GOALS.md: product purpose and desired user outcome;PRODUCT.md: externally observable behavior and safety;- this document: ownership, synchronization, conflict resolution, and process maturity;
UI_GUIDELINES.md: interaction and terminal decisions delegated by the product specification;CODING_STYLE.md: implementation and repository constraints;TESTING.md: verification strategy, evidence, and gates;PERFORMANCE.md: performance resource model, budgets, bottlenecks, measurement methods, benchmarks, profiling evidence, and regression criteria;ARTIFACT.md: repository build and release artifacts;TERMUX_PACKAGES.md: official Termux publication and deployment;- domain registries under
spec/model/: facts explicitly migrated to structured ownership.
A document has no authority outside its owned domain. Supporting documents never weaken a product safety guarantee. Tests and evidence verify requirements but do not redefine them. External policy may block an integration or deployment but never silently weakens product safety.
Stability and evidence
TJ-GOV-03. Expected change decreases from source and design through requirements and concepts to goals. Resolve a discrepancy at the most malleable layer that is actually wrong. Implementation convenience is not evidence that a more stable layer should change.
TJ-GOV-04. Every layer remains revisable when learning invalidates it. Intent refines downward from goals toward artifacts. Runtime observations and experimental evidence flow upward and may reopen source, design, requirements, concepts, or goals.
TJ-GOV-05. Normative status, expected stability, and evidence maturity are separate properties. An accepted requirement may depend on weakly evidenced assumptions. An observation may be strong evidence without becoming a requirement.
Assumptions and limitations are recorded explicitly and linked to affected requirements. Evidence states what was tested, where, with which inputs, and what remains unestablished. No evidence from one environment silently generalizes to another.
Refinement and convergence
TJ-GOV-06. Intermediate representations may diverge during active discovery. They converge at integration, release, and deployment gates. A gate never repairs tracked files, accepts stale derived output, or treats a warning as successful convergence.
A discrepancy is classified as one or more of:
- implementation defect;
- stale or incorrect requirement;
- incorrect or unstable concept;
- inadequate test or observation;
- unsupported environment;
- changed external dependency or policy;
- reproduction or attribution error;
- changed product goal.
TJ-GOV-07. A normative change names every affected stable identifier and states whether each is added, revised, split, merged, moved, superseded, or removed. The owning text, structured model, derived views, tests, evidence, and references converge in the same integration change.
Stable identifiers denote lineages, not immutable wording. A semantic revision denotes one exact meaning in that lineage. Initial migration uses revision 1 as a baseline and makes no claim about unrecorded history. A replacement preserves resolvable aliases for one release unless retaining an alias would create a safety ambiguity.
Conflict handling
TJ-GOV-08. A conflict exists when requirements with overlapping scope require incompatible outcomes, when multiple owners claim the same fact, or when a projection differs materially from its owner. Newer text does not win automatically.
Resolve a conflict by correcting an erroneous projection, narrowing scopes, declaring an explicit exception, or selecting one owner and removing the competing formulation. A same-domain conflict or an apparent weakening of safety stops work for an explicit decision. No tool, test, agent, or human may hide the conflict by weakening validation.
Progressive calcification
TJ-GOV-09. Exploratory processes may rely on human or agent judgment while concepts, inputs, and failure modes remain unstable. Record assumptions and evidence before treating repeated practice as policy.
TJ-GOV-10. Repeated processes become structured and mechanical only when their rule is precise, valuable, observable, and stable enough that enforcement reduces rather than conceals uncertainty. Prefer generation from one owner over post-hoc comparison of duplicated facts.
TJ-GOV-14. When a stable fact can be expressed faithfully as structured data, its registry is canonical. Specifications reference that registry, and build tooling generates source-code types, constants, tables, and user-facing projections from it. Generated outputs own no semantics and are never edited directly. When structured data cannot faithfully express the behavior, normative prose remains authoritative and the registry references it.
TJ-GOV-11. Every calcified rule has an explicit reopening path. When reality invalidates a check, preserve the evidence and block affected integration or publication. Revise the authoritative fact, migrate dependents, and then change the check. Bypass flags, ignored failures, and silent exceptions are forbidden.
Specification tooling
TJ-GOV-12. The specification tool is a validator, query engine, generator, graph navigator, and, only for stabilized transformations, refactoring engine. It is not a semantic authority. Humans and agents may make semantic decisions; mechanical checks establish only the properties they actually measure.
Phase 1 automation validates registered structure and generated projections. It does not claim that every normative sentence has been identified, that tests provide product coverage, or that two prose statements are semantically equivalent. Those claims require explicit mapping and semantic review.
Canonical Markdown and ZON may be edited directly during Phase 1. The noninteractive specification gate is authoritative for structural validity. Mutation commands are added only after their transformations and failure semantics have stabilized.
Agent document discovery
TJ-GOV-13. AGENTS.md contains a generated skill-shaped catalog of project documents. Catalog
entries have a stable name, task-oriented activation description, and repository-relative location.
They are project documents, not harness skills.
The catalog is generated from spec/model/documents.zon. Agents load every document whose
activation description matches their task and follow relevant links. Governance is loaded before
changing normative ownership, concepts, requirements, validation, or document authority.
Handwritten bootstrap instructions remain outside the generated region. Generation preserves those bytes exactly, requires one correctly ordered marker pair, escapes catalog text, and rejects invalid or duplicate entries.