docs: Phase 0 and Phase 1 contract-first gating documentation

[mikeylong]

Strategy check

• I read "docs/strategy.md"
• This PR strengthens the decision filter sentence (by documenting the canonical gate so it is executable in workflows)
• Enforcement timing is explicit: generation time (validate as gate)
• Violation handling is defined: blocked via non-zero exit codes; v2 category-based
• CLI behavior is tied to contract semantics, not free-form heuristics

What changed

• Phase 0: Added docs/contract-baseline.md describing the minimal authoritative contract (required fields, optional color policy, deprecated allowedColors), schema location, and validation entry points (validateContractStructure, evaluateContractCompliance, collectSurfaceDescriptors, runValidateCommand).
• Phase 1: Updated README.md and API.md to state that interfacectl validate is the canonical generation-time gate for contract compliance. All CI examples now use --exit-codes v2. Documented env vars: SURFACES_ROOT, SURFACES_CONTRACT, SURFACES_CONFIG, INTERFACECTL_EXIT_CODES (confirmed in code). Positioned enforce --mode fail as optional policy-on-diff.

Why it matters

Readers can understand the contract format without reading the JSON schema alone. Teams have a single recommended command (validate with v2) for gating. CI examples use stable exit codes. Env var names are locked and documented.

Contract and enforcement notes

1. No contract fields added or changed. Documentation only.
2. Enforcement point: generation time; validate is documented as the canonical gate.
3. Expected behavior on violation: non-zero exit (v2: 10/20/30 by category); already implemented.

Tests

No test changes. Verified: pnpm run build and pnpm run test pass. Ran interfacectl validate --root packages/interfacectl-cli/test/fixtures/minimal-project --contract contracts/ui.contract.json --exit-codes v2 from repo root; exit 0 when compliant.

Phase 0 and Phase 1 PR Review Checklist

• Changes are limited to Phase 0 or Phase 1 scope.
• No implementation of compile, explain, new validation rules, or schema changes.
• No CI job was added to enforce interfacectl.
• I read docs/strategy.md.
• I read docs/plans/contract-first-enforcement-alignment.md.
• This PR preserves the decision that validate is the canonical generation-time gate.
• The README planning constraint remains intact.
• Documentation clearly states that interfacectl validate is the canonical contract compliance gate.
• Documentation does not imply that enforce --mode fail is the canonical compliance gate.
• enforce --mode fail is referenced as optional policy-based enforcement on structural diff.
• All new or updated CI examples explicitly use --exit-codes v2.
• Environment variable names referenced in docs are confirmed in code.
• Docs describe the minimal authoritative contract and required fields (docs/contract-baseline.md).
• Deprecated contract elements (allowedColors) are called out explicitly.
• Docs point to real schema and validation entry points.
• Documented commands run successfully against existing fixtures.
• Gate alias: N/A (no gate command added).

Acceptance criteria satisfied

From docs/plans/phase-0-1-execution-plan.md:

Phase 0: (1) docs/contract-baseline.md describes minimal contract, optional color policy, deprecated allowedColors; (2) schema path and validation entry points named; (3) no schema or validator code changes.

Phase 1: (1) README and API state validate is recommended gate; CI command includes --exit-codes v2; (2) README CI example shows --exit-codes v2 and documents INTERFACECTL_EXIT_CODES; (3) No gate command added; (4) validate against minimal-project fixture exits 0 when compliant (verified).

Made with Cursor