Forge Platform

Handbook

Forge page contract v1

The page contract makes every durable Forge page consumable in layers — a C-level reader, an architect, a practitioner, and an agent should each be able to stop at their depth and still leave with the truth. It has two…

Updated

Enforced by forge-platform/scripts/check_page_contract.py (report-only by default; --strict fails on violations).

1. Frontmatter contract

Required keys (see schemas/doc_page_frontmatter.v1.schema.json):

Key Meaning
content_id Stable registry identity (forge.docs.<repo>.<slug>)
canonical_owner Owning repo/team
primary_persona c_level | engineering_leader | architect | practitioner | operator | agent
reader_stage discover | evaluate | adopt | operate | extend | troubleshoot
maturity defined | demonstrated | vision
evidence_level canonical_doc, example, run_evidence, narrative, …
last_reviewed ISO date of last human review

Recommended keys: claim_ids, source_refs, refresh_policy, next_action_human, next_action_agent, secondary_personas, and the optional agent_contract block (rendered as a styled panel by forge-autodoc).

2. Required sections

A conforming page answers these in order (heading names may vary; the linter matches by alias):

  1. Executive capsule — 3–5 sentences: what it is, why it matters, maturity.
  2. Who this is for — persona and stage.
  3. The problem this solves — user language before mechanism.
  4. How it works — the mechanism, honestly scoped to maturity.
  5. How it fits the ecosystem — neighbors, boundaries, contracts.
  6. Evidence and maturity — defined / demonstrated / vision, with proof.
  7. Trust boundary — what a human decides vs what automation does.
  8. How to use it — commands, examples, or next reading.
  9. Agent contract (optional but recommended) — from agent_contract frontmatter.
  10. Related / next — links by reader stage.

Sections 1–3 are the capsule layer (C-level stops here). Sections 4–7 are the architect layer. Sections 8–10 are the practitioner/agent layer.

3. Scope

The contract applies to durable strategic pages: standout notes, adoption and landing narratives, start-here guides, architecture cores. It does not apply to changelogs, meta indexes, API dumps, or generated artifacts.

Rollout: report-only linting first; strict enforcement flips per-site once the pilot set passes (see OPERATING-CADENCE.md).