Contracts — Pillar 2: Solution Mechanism

2026-08-19

How this repo works. Architecture, design rules, authority order, and integration contracts.

Authority Order

1. repo_owner_rules — Rules established by the repo owner
2. repo_governance — ADRs and governance docs in docs/adr/
3. architecture_spec — Architecture model in docs/architecture.md
4. contract_spec — MCP contract expectations in docs/repo-mcp-contract-expectation.md
5. framework_guidance — Cross-repo guidance from dirac-framework

Discovery Contract

• Resolve repo metadata through the workspace registry first
• Only load docs/agent/manifest.yaml when the registry declares a real manifest
• Use registry-declared entrypoints for fallback repos
• Use heuristic probing only as a last resort

Four-Pillar Canonical Structure

Every repo SHALL expose four pillar surfaces (ADR-0003):

Pillar	Resource	File
Rationale	repo://{repo}/capabilities	docs/context/capabilities.md
Solution Mechanism	repo://{repo}/contracts	docs/context/contracts.md
Deployment Instructions	repo://{repo}/workflows	docs/context/workflows.md
Documentation & Training	repo://{repo}/start-here	docs/agent/start-here.md

Integration Contracts

• MCP resources: workspace://* (workspace-level), repo://* (repo-level)
• Manifest schema: defined in docs/agent/manifest.yaml and docs/repo-mcp-contract-expectation.md
• Registry format: workspace-repo-registry.generated.json