Repository Governance & Spec Authority

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• README.md
• scripts/check-spec-authority.sh
• scripts/check-docs.sh
• docs/jazz-language-state.md (referenced in validation scripts)
• jazz-next/README.md

The Jazz project employs a strictly hierarchical governance model to manage the evolution of the language and its various implementation targets. This system distinguishes between canonical specifications, active implementation paths, and legacy reference code to ensure that the "source of truth" remains unambiguous during development.

The governance framework is enforced through both manual policy and automated verification scripts that check for normative claims and documentation consistency across the repository.

Sources: README.md:23-32, scripts/check-spec-authority.sh:1-5

Authority Hierarchy

The project defines a clear hierarchy of authority for language behavior. The canonical authority is centered on formal documentation and the active compiler implementation, rather than legacy prototypes.

Normative vs. Non-Normative Targets

• Canonical Authority: Defined by files located in docs/spec/* and the verified behavior/tests within the jazz-next/ directory.
• Non-Normative (Reference-Only): jazz2/ is designated as a design source for future ideas only. It is explicitly non-normative for current language behavior.
• Historical Reference: jazz-hs/ is treated as historical evidence and is not an implementation target.

Sources: README.md:24-26, AGENTS.md:3-10, jazz-next/README.md:3-6

Authority Flow Diagram

The following diagram illustrates how language authority flows from specifications to the active implementation, while bypassing legacy components.

Workspace Management Policy

To maintain the integrity of the authority hierarchy, the repository enforces strict read/write policies across different directories.

Directory	Status	Policy	Purpose
jazz-next/	Active	Read/Write	Only target for new compiler implementation work, APIs, and runtime changes.
jazz-hs/	Legacy	Read-Only	Historical reference implementation. No modifications allowed unless for legacy maintenance.
jazz2/	Experimental	Read-Only	Design source for future ideas and experimental reference code.

Sources: AGENTS.md:3-13, jazz-next/README.md:1-10

Change Control Process

The project distinguishes between semantic and non-semantic changes to determine the required level of governance.

• Semantic Changes: Any change affecting the language definition requires a formal Decision Record or RFC (Request for Comments) prior to implementation.
• Internal Changes: Non-semantic or internal implementation details may follow an "implementation-first" workflow, provided that documentation and tests are updated in the same commit or Pull Request.

Sources: README.md:28-30, scripts/check-spec-authority.sh:28

Change Workflow Sequence

The sequence below outlines the mandatory steps for implementing a semantic language change.

Automated Governance Enforcement

The repository utilizes shell scripts to programmatically enforce the governance policy and ensure documentation does not drift from the specified authority model.

Spec Authority Validation

The scripts/check-spec-authority.sh script verifies that:

1. README.md and docs/jazz-language-state.md do not make unsupported normative claims about jazz2.
2. The authority hierarchy correctly points to docs/spec/ and jazz-hs (for temporary authority/tests).
3. Hybrid semantic-change workflows are correctly documented.

Sources: scripts/check-spec-authority.sh:16-40

Documentation Consistency

The scripts/check-docs.sh script ensures synchronization between high-level status overviews and detailed state documentation.

• Verification: It checks for the existence of required headings like ### Implemented Today (verified) in the README.md.
• Cross-Linking: It mandates that the README.md contains a canonical link to docs/feature-status.md.
• Active Path Reference: It ensures both the README.md and docs/feature-status.md correctly reference jazz-next/ as the active compiler path.

Sources: scripts/check-docs.sh:25-45

Conclusion

Repository governance in Jazz is structured to prevent implementation drift by anchoring the "source of truth" in the docs/spec/ directory and the jazz-next/ implementation. By designating legacy paths as read-only and requiring RFCs for semantic changes, the project ensures a controlled evolution of the functional language.

Sources: README.md:23-32, AGENTS.md:3-13