Skip to content

Composition publication boundary

Composition · Canonical English日本語

The composition branch owns one provider publication boundary for the reusable composition system. It replaces the former assumption that Skill and Webapp documentation must be published from independent template authorities. Agent Skill, Website, and Web application semantics now live as distinct artifact responsibilities inside one Composition provider, with shared Web semantics owned once by foundation.web.

Composition owns its catalog declarations and validates them with its local scripts/publication_catalog.py. Integration independently reads this data format when assembling a publication. Provider CI needs no Integration checkout or pin.

This is a development/publication dependency only. The Composer runtime, managed-repository lifecycle, lock/transaction machinery, recipes, and consumer validators do not import or invoke the Integration publication protocol.

Reader-facing boundary

docs/publication-catalog.json is a schema-version-3 allowlist. The local parser checks its fields, paths and sources. Each document needs an id and source; home and optional default to false. Integration includes new entries automatically. Composition-specific validation additionally requires README.md to remain the provider home and docs/glossary.yml to remain the Composition terminology declaration.

The catalog publishes explanatory Markdown for:

  • composition architecture and the deterministic composer;
  • the Website/Web application selection boundary and the shared foundation.web model;
  • the Agent Skill artifact model;
  • the Website artifact model and first-use path;
  • the Web application artifact model and first-use path;
  • reusable runtime, CLI, MCP, MCP Apps, PWA, browser, and service capabilities;
  • reusable composition-state, contract-evolution, implementation-evidence, release-execution, release-evidence, and release-bundle lifecycle contracts;
  • the canonical independent clean-room evaluation entry point that routes evaluators to the formal protocol, scorecard guide, scorecard schema, and output sequence; and
  • the installer-release record at release/README.md, which explains the Composition provider's immutable installer, distributed Skill-source, and selected toolchain identities; and
  • one consolidated authority-migration history that explains why former monolithic Skill/Webapp responsibilities moved to their present authorities and points to immutable PR provenance for stage-level detail.

The publication home is the branch README.md. The optional source-navigation graph starts at the authority’s index.md; reader menus and public URLs belong to Site.

Markdown classification boundary

The catalog is an allowlist, but absence from the allowlist must also be intentional. Composition therefore closes the repository-source Markdown maintenance boundary with two additional Composition-owned declarations: translations/manifest.json for non-authoritative derivatives and docs/publication-classification.json for explicit non-publication exclusions. Neither declaration is part of the generic Integration publication protocol.

Every Markdown file in the Composition source tree must be exactly one of:

  1. published — its source path appears in docs/publication-catalog.json under documents;
  2. translation-declared — its path appears as a translation in translations/manifest.json, making it a non-authoritative derivative of a canonical document; or
  3. explicitly excluded — its source path appears in docs/publication-classification.json with a non-empty maintenance reason.

Local execution-state directories such as Git metadata, virtual environments, tool caches are not repository source and are excluded from discovery. A newly introduced Markdown class such as docs/guides/*.md, a new component-local documentation subtree, a new top-level Markdown file, or an undeclared translation therefore fails validation until its publication intent is classified explicitly.

An exclusion does not suppress a known reader-facing requirement: the existing Composition-owned reader-coverage rules still require provider roots, current architecture, the consolidated authority-migration history, schema/catalog guides, and reader material declared by production components to be published. Published, translation-declared, and explicitly excluded Markdown classes are pairwise disjoint.

The current explicit exclusions are:

  • operational consumer-agent instructions (components/artifact.skill-core/files/AGENTS.md);
  • supplemental WebMCP selection notes (docs/guides/webmcp-capability.md), because the canonical reader-facing capability authority is components/capability.webmcp/files/WEBMCP.md and is indexed from docs/index.md;
  • the stage-specific PR2 and PR3 authority-migration notes (docs/migrations/pr2-skill-capabilities.md and docs/migrations/pr3-webapp-lifecycle.md), which are retained as Composition authority maintenance provenance while the consolidated history and immutable PR records form the reader-facing history surface;
  • non-production executable-fixture guidance (examples/README.md);
  • repository-facing Composition skill instructions (skills/composition/SKILL.md), which are distributed as executable skill material rather than canonical reader publication; and
  • provider-owned translation maintenance guidance (translations/README.md).

Provider-owned translation derivatives are not duplicated in the exclusion list. Their paths are classified solely by translations/manifest.json; the translation validator separately enforces canonical-path mirroring, current canonical blob identity, notice requirements, surface eligibility, and complete declaration of translation Markdown.

The classification file and translation manifest are Composition maintenance metadata, not Site publication assets, and do not change publication-catalog schema version 3.

Machine-readable boundary

Machine-readable source authorities are published as supporting assets rather than rendered documentation. Composition-specific coverage validation requires the catalog assets to cover:

  • catalog/catalog.json;
  • all three production recipes (skill, website, and webapp);
  • every top-level composition JSON Schema, including the immutable skill-installer release schema;
  • the stable release/composition-installer.json identity descriptor;
  • every production component descriptor, including foundation.web;
  • shared Web foundation contract/schema seeds;
  • Website domain contracts and schemas;
  • Webapp domain contracts and schemas;
  • reusable lifecycle contract/schema seeds;
  • the consumer composition-lock schema; and
  • the formal clean-room evaluation protocol, scorecard guide, and scorecard schema.

Evaluation materials are maintainer/evaluator authorities rather than ordinary materialized consumer contracts. They are published as a reader entry document plus exact supporting assets; they do not extend the consumer agent.json bootstrap with an evaluator mode.

The stable installer descriptor separates three full-SHA roles: the remote installer script revision, the installed skill-source revision, and the Composition toolchain revision selected by that skill. Repository CI verifies those identities against Git history, the pinned installer source, the skill runtime manifest, the runtime-lock digest, and strict toolchain -> skill source -> installer -> publication ancestry. release/composition-installer.json is the machine-readable authority for those identities. The separately published installer-release record at release/README.md explains that provider/maintainer release boundary and links to canonical consumer operation; it does not replace consumer bootstrap, installation, replacement, update, or product-release guidance.

The local catalog parser validates the generic asset declarations, source existence, path safety, symlink boundary, overlap rules, and the prohibition on undeclared Markdown inside asset trees. Composition then validates that those generic assets cover the machine-readable authorities required by its own production catalog.

A machine-readable file is not public merely because it exists in the branch. It must be covered by an explicit asset entry.

contracts/manifest.json is deliberately absent from the source publication assets. It is a deterministic generated consumer material owned by lifecycle.contract-evolution; no canonical source file exists in the composition checkout. The publication instead exposes the component registrations and schemas from which the composer generates the manifest.

Authority and URL model

The provider identity is composition. Agent Skill, Website, and Web application remain distinct artifact semantics inside that provider, not independent source authorities. Website and Webapp share foundation.web rather than reconstructing duplicate browser identity, route, or viewport authorities. Integration may group the three artifact families separately for readers, but it must not reconstruct separate canonical source ownership for them.

This repository is not yet production-facing, so the composition migration does not preserve the former provider URL namespace merely for backward compatibility. Reader information architecture is a Site-owned concern and is handled separately from this provider allowlist.

Glossary ownership

docs/glossary.yml is the Composition-owned terminology source. Its record semantics remain validated by Composition after the generic Integration protocol confirms that the catalog declares an existing safe .yml glossary source.

It retains templates-skill-profile because Policy legitimately relates Policy profiles to Skill profiles, but definitions that depended on the retired copyable-template architecture are not preserved. Generic composition/lifecycle concepts use composition-owned IDs rather than being mislabeled as Webapp-only, Website-only, or Skill-only concepts.

The glossary file is encoded as strict JSON, which is a valid YAML 1.2 subset. This lets Composition validate its provider-specific terminology semantics with the Python standard library while remaining compatible with the Integration glossary model.

Local validation

Run provider-owned checks; no Integration checkout or parser pin is required:

python -I scripts/materialize_publication.py --source-root .
python -I scripts/publication_catalog.py --source-root .
python -I scripts/validate_publication.py

After changing component semantics, run the materializer with --refresh from the committed source, and commit the generated projections. These are build provenance, not downstream adoption requirements. Integration snapshots this branch independently. Site owns public routes, audience navigation and presentation.