The contract grammar
Five contracts. One question each.
A governance framework is only as real as its grammar. These five contracts are the public shape of the system — what a page may be, who may write it, what may link to it, where the boundary sits, and what done means. The YAML is the pattern. Your domain fills the values.
contracts/page_types.yaml
What a page needs at each quality tier.
WordPress has draft and published. Constitutional CMS has a continuous quality spectrum. Pages graduate and degrade from evidence, not editorial mood.
entity_page:
url_pattern: "/entities/{entity-slug}"
tiers:
FULL:
required_fields:
- entity_name
- validated_metric
- source_snapshot
- narrative_block
- json_ld_schema
min_word_count: 800
schema_emission: true
internal_links: true
BASIC:
required_fields:
- entity_name
- validated_metric
min_word_count: 200
SHELL:
required_fields: [entity_name]
schema_emission: false
internal_links: false
SUPPRESS:
trigger: "source permanently unavailable"contracts/enrichment_stages.yaml
Which stage writes which state, and the gate that must pass first.
Every stage has exactly one owner. No two agents write the same table. Bad data is rejected at ingestion, not discovered in production.
stages:
- name: telemetry_ingestion
writes_to: raw_observations
owner: agent_1
quality_gate:
- "carrier field is not Various or Unknown"
- "price_usd > 0"
- name: snapshot_materialization
reads_from:
- raw_observations
- operational_data
writes_to: entity_snapshots
owner: agent_1
- name: narrative_enrichment
writes_to: entity_snapshots.narrative_block
owner: agent_5
quality_gate:
- "word_count >= 800"
- "no confabulated statistics"
- name: schema_assembly
owner: agent_1
quality_gate:
- "page must be BASIC or above"
- "schema fields sourced from snapshot, never computed at render"contracts/link_rules.yaml
What is allowed to link to what.
Broken internal links at scale are the common failure mode in programmatic SEO. Integrity is enforced by contract, not by a later crawl.
rules:
- name: no_phantom_links
applies_to: all_page_types
enforcement: hard_block
- name: shell_isolation
applies_to: pages_at_tier_SHELL
enforcement: hard_block
- name: hub_to_children
applies_to: hub_page
allowed_targets: [entity_page]
constraint: "target.parent == source.id"
- name: no_upward_links_from_thin
enforcement: soft_warn
rationale: "Thin pages must not dilute authority of FULL pages"contracts/snapshot_boundary.yaml
The database schema is the inter-agent contract.
Write agents produce snapshot rows. Read agents consume them. If a field is missing, the page degrades to SHELL. The system fails safe, not silent.
principle: "The database schema is the inter-agent contract"
boundaries:
write_agents: [agent_1, agent_5]
read_agents: [agent_2]
verify_agents: [agent_3]
rules:
- Write agents produce snapshot rows. Read agents consume them.
- Read agents NEVER compute primary data.
- Schema changes require a reviewable migration.
staleness_guard:
fresh: "Serve from snapshot (sub-50ms)"
stale: "Fall through, logged as anomaly"
missing: "Render SHELL template"
failure_mode: fail_safe_not_silentcontracts/sprints/
Scope, ownership, and what done means on the live site.
A sprint is not finished when the PR merges. It is finished when production proves the contracts. That closes the gap between CI and the live surface.
sprint:
name: Quality Recovery
scope:
in: [Unify claim authority, Restore source snapshots, Fix broken links]
out: [New visual layer, New page types, Infrastructure]
acceptance_gates:
- Same public claim across page types and APIs
- Zero broken internal links emitted
- Resolver and rendered output agree on indexability
exit_criteria:
- All gates pass on the LIVE SITE
- Not when PRs merge — when production proves itThe pattern is open
Copy the contracts. Keep your tuning.
The grammar ships publicly. The thresholds, registries, and recipes that make one implementation an advantage stay private — that is the boundary, not an omission.