# Specification governance

Document: SPEC-000. Revision: 0.4. Date: 2026-10-24. Lifecycle: Partially approved; cyclic-testing deployment authorization confirmed under D-159. Supersedes: none.

## Authority and status

The human develops and approves the specification. The LLM reviews it, identifies gaps and conflicts, proposes refinements, and writes code when authorised. An LLM-generated design remains a proposal until accepted by the human.

The confirmed requirement register in [SPEC-001](001-product.md) records the initial brief and explicit answers. These requirements remain authoritative while the detailed design is in draft. A draft document is not permission to ignore a confirmed requirement.

The following labels apply throughout the specification:

| Label | Meaning |
| --- | --- |
| CONFIRMED | Explicit human requirement or accepted decision; cite its source in the decision or change history |
| PROPOSED | A specific recommendation for review; not implementation authority |
| OPEN | A question that has no accepted answer |
| DEFERRED | A feature or decision deliberately postponed by the human; proposals to postpone remain proposals |

`MUST`, `SHOULD`, and `MAY` express obligation, recommendation, and permission within a requirement's status. A proposed MUST is still proposed. Research observations establish constraints, not product approval.

## Change workflow

1. The human adds or changes requirements, or asks the LLM to prepare a draft reflecting the human's intent.
2. Review the change for ambiguous behaviour, conflicts, security implications, deployment impact, and acceptance criteria.
3. Record accepted decisions and unresolved questions. Do not infer acceptance from elapsed time or an unanswered question.
4. Once implementation is requested and the affected behaviour is sufficiently specified, implement against the accepted specification revision.
5. Validate code against the affected requirements and update traceability. Ship the matching specification and code together.

A simple bug fix may restore behaviour already specified without changing the specification. Record the relevant requirement and the regression scenario. If the expected behaviour is disputed or absent, resolve that ambiguity before changing it. A larger fix may require amendments to several documents.

The specification describes intended behaviour; an implementation inventory describes what is implemented. Unimplemented requirements may remain active when their delivery status is explicit. Existing code that contradicts an active requirement is a defect or a pending migration, not an implicit specification amendment.

## Cyclic-testing deployment authorization (D-159)

During the current cyclic-testing phase, validated fixes and sufficiently specified requested changes are authorized for deployment to the existing testing services without a separate human review, confirmation or approval before each deployment. Continue implementation, relevant checks, deployment and rollout verification within the accepted scope. This standing authorization lasts until the human ends the testing phase or revokes it, and supersedes earlier per-release approval gates.

Engineering review, automated tests, specification consistency, release evidence and the Cloudflare rollout checks in `docs/deployment.md` still apply. Report failed validation or deployment evidence accurately and repair failures; do not turn routine release checks into a human sign-off gate. Human ownership of unresolved product behavior remains unchanged.

## Proposed document lifecycle

Documents move through Draft, Approved, Deprecated, and Superseded states. The human approves a document or a precisely identified part of it. Partial approval lists the affected requirement or decision IDs.

- Approved documents have a revision, approval date, and approval scope.
- Deprecated documents remain applicable only to their stated supported versions until a stated retirement condition.
- Superseded documents name the replacement and the exact sections or requirements replaced. The replacement links back.
- A newer timestamp alone does not supersede anything. Conflicts require an explicit resolution.
- Preserve stable requirement IDs. Never recycle a retired ID for unrelated behaviour.
- Describe the final active behaviour in the active specification; keep historical reasoning in the decision log and version history.

Proposed precedence: explicit accepted supersession, then accepted requirement/decision, then approved detailed specification. Unresolved conflict stops only the affected implementation. The initial requirement register is not permanently privileged over later human-approved amendments.

## Proposed implementation gate

Before implementing a feature, record its active requirement IDs, accepted decisions, observable behaviour, failure cases, and acceptance scenarios. For protocol work also specify wire formats, authentication, state transitions, error handling, compatibility, and limits.

Implementation choices that do not alter specified behaviour may be made during coding. Architectural choices, privacy guarantees, platform support, and user-visible policy changes must not be hidden as implementation details.

A release identifies its supported protocol versions, platform matrix, specification revisions, known deviations, and implementation coverage. A temporary deviation needs an explicit human-approved scope and resolution plan; merely listing it does not make incompatible code conformant.

## Required specification sections

CONFIRMED under D-013 and R-049–R-051: every specification document must contain the following exact section headings. This applies to the numbered SPEC documents and any future document specifying implementation behaviour. The index, decision/question registers, research notes, and changelog are supporting records rather than implementation specifications.

- **Configuration:** describe every configuration property used by the code covered by the specification, including its default. Record the property name, purpose, type/allowed values, units where applicable, scope, and default status. Before implementation, also resolve required values with no default, validation, omission/null semantics, inheritance and override precedence, how values are supplied, when changes take effect, and secret handling. Reference the owning specification for shared properties instead of defining competing defaults. Identify fixed requirements separately; do not turn them into optional settings. If no configuration applies, state that explicitly.
- **Testing:** describe the unit tests for the code covered by the specification, including expected outcomes for normal behaviour, boundaries, invalid input, configuration/default handling, permissions, and failure paths where relevant. Name the units or responsibilities being tested. Distinguish unit tests from integration, end-to-end, platform, performance, and security validation. If the specification has no code responsibilities, state that and identify the appropriate document checks; do not invent an application unit merely to fill the section.
- **Acceptance criteria:** provide a bullet list of specific observable conditions for correct and complete implementation. Each criterion must make its pass/fail outcome clear and identify the relevant fixture, scope, or threshold when needed. Link cross-cutting scenarios where useful. Passing unit tests alone does not establish platform, interoperability, or security claims. A partial milestone does not establish completion of the full specification.

Draft configuration names may be logical names pending the final API/environment-variable schema. Label them as proposed. Use `OPEN — not selected` for an unresolved default, `Required — no default` only where an explicit value is required by the proposed/accepted contract, and `Not applicable` only where no setting exists. An open value is a design gap, not a runtime value, unlimited setting, disabled feature, or permission to guess during coding. Approval of this section structure does not approve the draft defaults or designs recorded elsewhere.

CONFIRMED D-014/R-052: maintain separate [client](005-clients.md) and [server](008-server.md) specifications. Each owns its component's behaviour, configuration, tests and acceptance criteria; shared protocol, security, media and data contracts remain in their topic specifications and are referenced by both. Do not duplicate a server permission algorithm or persisted default in the client specification merely because the client displays it.

Draft 0.3 authoring refinement: classify each inventory entry as a deployment setting, administrative policy, user preference, fixed protocol rule, negotiated value, or operational state. Only the first three are configuration. State has initial conditions and transition rules rather than configurable defaults. Protocol profiles and platform implementation choices are not automatically user settings. Supporting review reports are historical records, not additional implementation specifications.

Before implementation, each configuration schema must identify its canonical owner, authorised writer, exact type/units/range, default and approval status, omission/null/zero meaning, inheritance, source precedence, change timing, persistence and schema-version compatibility. An inherited boolean must distinguish inheritance from an explicit false value; omission must not weaken an ancestor's restriction. Incompatible, unknown or unresolved values must not silently produce a permissive effective configuration. Wire/API spellings and migration rules remain OPEN until the relevant profile is selected.

Milestone acceptance must identify the applicable subset of each cross-cutting scenario. A desired feature may be absent with a recorded gap, but any implementation delivered must satisfy its applicable security and correctness criteria. A historical review finding is addressed by an amendment only to the stated extent; incorporation into a draft does not select an OPEN mechanism or approve a new numeric default.

## Licensing and independent implementations

CONFIRMED D-035: original project code, specifications, documentation and examples use Apache-2.0, with the unmodified licence text in [LICENSE](../LICENSE) and project attribution in [NOTICE](../NOTICE). Explicit existing file licences and third-party licences remain applicable to their respective material. The [README licensing statement](../README.md#licensing) records scope and the existing Gentoo ebuild exception.

Independent clients, servers and other protocol implementations may use any licence, including proprietary licences. Implementing the protocol or communicating with an implementation does not require adopting the reference implementation's licence. Reusing protected project material remains subject to its applicable licence. This policy adds no separate protocol-wide patent grant; the standard Apache 2.0 patent and trademark terms apply. Technical conformance and operator authorisation remain separate from copyright licensing.

Package metadata identifies original project material as `Apache-2.0`; distribution processes include the project licence and attribution without replacing third-party notices. SPEC-005 owns the desktop archive and Gentoo packaging contract. This decision does not select governance for third-party extensions or protocol revisions under Q-30.

## Configuration

No application runtime configuration is owned by this governance specification. The required section names, human approval authority, and specification-first workflow are fixed authoring requirements, not configurable switches. Default values: not applicable. A future specification-validation tool must document its own settings and defaults before implementation.

## Testing

Licensing document checks compare LICENSE with the official Apache 2.0 text, verify package metadata and the README scope statement, and confirm that explicit file exceptions and third-party notices remain intact. Archive checks belong to SPEC-005; these checks do not require application unit tests.

There is no application code in scope and therefore no application unit-test suite to prescribe here. Document validation must check required headings, nonempty configuration/testing sections, a nonempty acceptance bullet list, unique identifiers, resolvable references, default status, and explicit supersession links. If a validator is later implemented, its unit tests must cover valid documents and rejection of each malformed/missing case, including distinguishing supporting records from specifications and preserving legitimate `Not applicable` entries.

## Acceptance criteria

- During D-159 cyclic testing, a validated in-scope change proceeds through deployment and rollout verification without an additional human approval step; the release records evidence and remaining limitations.

- The repository contains the unmodified Apache 2.0 licence, project attribution and an explicit independent-implementation policy under D-035; package metadata agrees with the selection and existing separately licensed material retains its notices.
- Every active implementation specification contains exactly one `Configuration`, one `Testing`, and one `Acceptance criteria` section; each contains the information required above.
- For each documented code change, its review record identifies the applicable specification revision and requirement IDs; no proposed choice is represented as human-approved without an accepted decision.
- Comparing a feature's code configuration schema with its owning specification reveals no undocumented property or different default; unresolved defaults relevant to that feature have been resolved before implementation.
- Every implementation specification states concrete unit-test coverage or explains why it owns no code, and gives a bullet list of observable completion criteria.
- Every superseded requirement identifies its replacement and scope; traversing those links yields an unambiguous active requirement. Deprecation states the supported versions and retirement condition.
- A release record distinguishes verified, partial, and unimplemented requirements and identifies any approved deviation; a partial milestone is not labelled complete implementation of the full specification.
- Every configuration entry is classified, has one canonical owner, and distinguishes inherited/omitted values from explicit settings; state and fixed protocol requirements are not exposed as invented operator switches.

## Current review state

The initial review paragraphs below are historical; their unselected/no-implementation statements are superseded within the explicit later scopes by D-024/D-049, D-159 and D-167. Current presentation behavior is owned by SPEC-024, with the native client increment preceding managed SFU evaluation. Human selection of future material behavior remains required; routine in-scope deployment does not gain a new approval gate.

The initial brief and decisions D-001–D-023 are confirmed, with R-016 explicitly refined by D-017. Draft 0.3 incorporates review RV-01–RV-13 into the component/shared contracts; detailed mechanisms P-011–P-022 remain proposed where not decided by the human. Delivery priorities and early test scope are accepted only to the extent recorded in the decision register. No cryptographic suite, federation wire protocol, programming language, media provider, or client toolkit has been selected by this revision. Application implementation remains not started and is not authorised by these amendments.

Subsequent request on 2026-10-18: the human requested the first build using the committed GitHub specifications. This supplies implementation authority under workflow step 4 for sufficiently specified behaviour. It does not silently resolve OPEN choices or approve proposed mechanisms. See the [implementation request record](decisions.md#implementation-request--2026-10-18) and [first-build preparation](reviews/2026-10-18-first-build-readiness.md).

Delegated resolution: D-024 records the human’s subsequent instruction to resolve the remaining V1 choices and implement. D-025–D-031 and the revision 0.4 V1 sections are implementation authority within that delegation. The original human requirements remain authoritative; approval of unrelated later features is not implied.

Current phase under D-049 (2026-10-18): the human explicitly confirmed application implementation and requested the GitHub repository update. This replaces the initial specification-only restriction in AGENTS.md. Review and implement sufficiently specified requested behavior; unresolved material choices remain explicit and do not become accepted merely because implementation has begun.