Publication catalog¶

The policy branch publishes a branch-owned allowlist of human-readable documentation, supporting public assets, and canonical terminology input through docs/publication-catalog.json. The independent Integration authority combines this catalog with Composition into the versioned Publication Bundle. Site remains on its historical reviewed inputs until explicitly adopted; it alone owns Pages rendering and deployment. Skill and Web application remain Composition concepts, not separate provider branches.

Ownership¶

policy owns each document's stable local ID, canonical Markdown source path, optionality, the publication landing document, explicit public asset roots, and its canonical docs/glossary.yml terminology source. The effective cross-branch document identity is policy:<document-id>. Glossary term identity is independent of document identity and follows the repository-wide stable term ID contract.

integration owns the generic schema-v3 publication protocol, public destinations, semantic navigation, reviewed provider locks and integrated glossary model. Site owns portal presentation, rendering, browser runtime and Pages deployment. Policy consumes the generic protocol from a reviewed full Integration commit SHA; it does not maintain a second parser, path validator or asset-tree implementation.

policy continues to run only its branch-local documentation build and must not gain a Pages deployment route. The catalog field home: true identifies the landing document for the policy section. It does not select the global portal home.

Canonical language and translations¶

English is the canonical language for maintained repository documentation and for glossary definitions. Every document source listed in docs/publication-catalog.json therefore identifies an English canonical document. A translation is a non-authoritative derivative and must not define independent requirements or override the English source.

Translations mirror the canonical path below translations/<language>/. For example, the Japanese translation of docs/overview.md is translations/ja/docs/overview.md. translations/manifest.json records each canonical/translation relationship and the Git blob identity of the canonical bytes against which the translation was reviewed. Changing canonical bytes therefore makes the translation record stale until the translation is reviewed and the synchronization record is deliberately updated.

Glossary localized_labels are not translated definitions. They are lexical discovery metadata that resolve to the same stable term ID and canonical English meaning.

Translations are not entries in the publication catalog. Integration derives translation availability from authority-owned manifests and may expose qualified derivative routes while preserving the one-way authority relationship and keeping the English document canonical.

Schema version¶

The local publication parser accepts integer schema version 3. Legacy publication-catalog schema versions 1 and 2 are retired and fail closed. Schema version 3 defines the current Markdown document and explicit asset contracts and additionally permits one canonical glossary declaration:

{
  "schema_version": 3,
  "documents": [
    {
      "id": "overview",
      "source": "docs/overview.md",
      "optional": false,
      "home": true
    }
  ],
  "assets": [
    {
      "source": "docs/assets",
      "destination": "assets",
      "optional": false
    }
  ],
  "glossary": {
    "source": "docs/glossary.yml"
  }
}

Each document identifies id and source; optional and home default to false. A required document source must identify an existing regular Markdown file. An optional document source may be absent, but when present it must also be a regular Markdown file. Exactly one non-optional document is the publication landing page.

Each schema-v3 asset contains exactly source, destination, and optional. Asset destinations are relative to the policy namespace in the generated site. Markdown files are forbidden inside asset roots because every published Markdown page must be named explicitly in documents. Asset roots must not contain a nested .git subtree in any letter case.

The optional schema-v3 glossary object contains exactly source. When present, it identifies an existing regular .yml file within the provider source root. It must not traverse a symbolic link and must not overlap an asset source. Individual glossary terms are not catalog entries; adding a term or a localized lexical label to an already declared glossary does not require a catalog change.

All source and destination values are portable relative POSIX paths. They may not be absolute, contain empty, . or .. components, use backslashes or colons, enter a .git subtree in any letter case, traverse symbolic links, or escape the declared source root.

Validation¶

The canonical generic validator is Integration's stdlib-only integration/publication_contract.py. Policy documentation CI consumes the exact implementation accepted by P5 bootstrap #894–#896 at full commit SHA a30699cf7dc56bf3ef7a1b6fd8f6ffd45cdd426d. The workflow sparse-checks out that immutable revision and runs it against the Policy source root; it never executes a mutable integration branch tip.

For local reproduction, make a separate checkout of that exact Integration revision available at a path of your choice, then run:

INTEGRATION_PUBLICATION_PROTOCOL_ROOT=/path/to/integration-checkout-at-a30699cf7dc56bf3ef7a1b6fd8f6ffd45cdd426d
python -I "$INTEGRATION_PUBLICATION_PROTOCOL_ROOT/integration/publication_contract.py" \
  --source-root . \
  --catalog docs/publication-catalog.json
python scripts/validate_translations.py

The generic protocol rejects duplicate JSON members, unsupported fields, unsafe or symbolic-link paths, duplicate IDs and destinations, invalid home declarations, missing required sources, any catalog schema version other than integer 3, malformed glossary declarations, Markdown smuggling through asset trees, and glossary/asset source overlap. Those rules are defined and tested by Integration rather than copied into Policy.

Policy-owned tests continue to verify Policy-specific declarations and semantics, including the expected Policy landing document, glossary declaration, translation relationships, reader/navigation structure, and documentation build boundary.

The Integration producer independently parses and validates the glossary content itself, including its schema, stable term IDs, localized labels, external authority metadata, cross-provider term-ID uniqueness, related-term resolution, and exact provider revision provenance.

The translation validator rejects unsafe or unmirrored translation paths, translations of non-published canonical documents, missing non-authoritative notices for Japanese translations, duplicate translation declarations, and structurally inconsistent synchronization metadata. Normal preflight allows stale derivatives while reporting reviewed/current canonical blob identities; direct validator invocation remains a strict freshness check. Integration determines publication availability, and no validation command updates synchronization hashes.

When exact catalog closure requires a new reader mapping, qualify the Policy candidate against an exact Integration candidate that owns the corresponding non-active staging mapping. Policy declares source identities and consumes that compatibility boundary; it never owns Integration reader IA. After the Policy candidate merges, explicitly promote the exact merged SHA and intended mapping into Integration, requalify, obtain review, and STOP at the Integration release.

Provider merge, candidate compatibility and Integration promotion are distinct. Site adoption and deployment require separate human instructions and are not completion requirements for upstream Policy/Integration publication work.

Maintainer publications¶

The following existing English sources are active Policy publication entries. These are stable Policy-side document IDs and source identities; Integration owns their reader destinations, semantic navigation and staging-to-active promotion. docs/publication-catalog.json remains the sole Policy publication allowlist.

All four correspond to the Policy candidates in the landed Site audience design at Site revision af55c7dc0176dd24393b4296b43c8e31d6171a11. That frozen inventory records historical exposure; this correspondence neither rewrites it nor imports Site reader taxonomy into Policy. No missing canonical source needed to be authored for these four identities.

The repository-local documentation index (source) links the contribution and workflow entry points. The ADR index links ADR-0008 and ADR-0009 through their canonical relative document paths. The three published layer indexes retain their catalog-only link contract.

Integration includes all declared reader documents automatically. New document identities need no curated Integration route or staging entry. Site alone assigns reader destinations, audience navigation and presentation. Policy owns the document sources and meanings.

Provider CI validates the local catalog. Integration and Site publish asynchronously, with exact input revisions recorded in their artifacts as provenance. Translation availability is derived from the provider's manifest; English remains canonical.