Spec: F105 — Lumi Contract Graph

Status: Derived from the canonical F105 CUE contract: partial.

1. Problem & CEO Job

Job: trust the signal. A completion claim is dishonest when registry, spec, code, collected tests, platform implementation, and release evidence disagree. F105 turns the existing Markdown rails into executable CUE contracts, resolves them against repository reality, and reports supported, missing, stale, orphaned, or unverified claims.

2. User Stories and Product Intent

The canonical atomic requirements, policies, implementation links, and proof IDs are in F105.cue. This section is deliberately non-duplicative: it explains the outcome a reviewer or agent should experience, not a parallel acceptance table.

• An engineer or agent gets a precise, deterministic explanation for an unsupported claim and the smallest legitimate next action—not a path to soften the claim.
• A reviewer sees generated traceability, collection status, execution evidence, and gaps as separate facts, so a pretty Markdown checkbox cannot substitute for a real proof.
• A hostile or mistaken contract cannot escape the repository, select arbitrary commands, or turn an existing but skipped test into evidence.
• Product judgment remains visibly separate from declared-contract completeness, traceability, automated execution, and live/device evidence.

3. Scope Boundaries

• In: pinned CUE schemas/contracts; CUE validation/export; deterministic Python repository proof; public-surface inventory; safe registered runner adapters; generated graph/gap/ traceability views; F103 vertical pilot; CI and Make integration; ordered migration plan.
• Out: replacing human product judgment, remote evaluation services, an LLM pass/fail judge, a database, arbitrary test-command execution, or bulk migration of unverified feature claims.

4. Data Model

No production database model. Canonical data is CUE committed to Git:

contracts/schema/feature.v1.cue
contracts/features/F<NN>.cue
contracts/generated/{graph.json,gaps.json,traceability.md}

Each contract defines feature identity, scope atoms, public surfaces, atomic requirements, implementation locators, proof declarations, controlled proof policies, and explicit gaps. Derived maturity is computed from resolved code, collected proof declarations, current execution evidence, and live-proof expiration; no editable completion flag exists.

5. API Contract

No product HTTP endpoint. The local CLI is the public interface:

Every diagnostic has a stable LCG- code, feature/requirement context when available, observed fact, expected invariant, safe next action, and machine-readable JSON form.

6. UI / UX

n/a — developer infrastructure. The agent-facing experience is the CLI output: concise first, stable JSON available, no vague “invalid contract” message, and no recommendation to weaken a requirement to pass.

7. Test Plan

See f105-lumi-contract-graph.md. The verifier has hermetic valid and mutant fixtures written before the engine behavior. The F103 pilot adds stable IDs to real pytest and Vitest proofs, exposes missing browser, grounding, platform, and OpenAPI evidence as gaps, and demonstrates mutation strength against a critical tenant rule via the disposable make contract-mutation gate. The F79 slice adds a fast source/docs parity gate for both mobile shells while keeping named-device proof as a separate gap.

8. Current Behavior

The Contract Graph exists as a CUE v1 schema, a deterministic Python resolver, named Make targets, and an expanding set of audited feature contracts. It is intentionally not closed. Current contract, registry, dependency, inventory, and declared-proof counts are generated into contracts/generated/graph.json and contracts/generated/gaps.json; those artifacts and make contract-validate are authoritative, not a copied number in this spec. Migrated features remain partial wherever their CUE contracts declare browser, native, live-provider, security, architectural, or product-decision gaps. The graph exposes those gaps rather than preserving prior green status claims.

9. Error States

10. Diagrams & Docs Touched

• deploy/DIAGRAMS.md: Contract Graph fast gate and evidence flow in CI.
• docs/ENGINEERING.md, CLAUDE.md, AGENTS.md, CONTRIBUTING.md: shrink manual proof rules only after their executable gate exists.
• docs/MVP_SCOPE.md: F105 registry entry now; later status derives from generated material.
• ADR-041 records the structural decision and CUE escape path.

11. Implementation Audit (2026-07-13)

Built foundation and pilot, with deliberate partial status. Audit evidence that drove the design:

1. F103 registry says ✅; its spec says draft; its declared E2E proof is absent and several historical test locations are stale.
2. The initial audit found Android’s map at three top-level destinations (Assistant, Business, More) while iOS had five assistant-first tabs; current main now carries the five-tab Android reconciliation and F103 native report source, while platform proof remains open.
3. scripts/check_docs_truth.py proves a useful precedent for deterministic docs checks but cannot trace an atomic requirement through code, test collection, and execution evidence.
4. CUE v0.17.0 is the pinned canonical validator/exporter; contracts are exported before Python resolves repository facts.

12. Open Questions / Decisions

• CUE version upgrades require an ADR amendment, migration fixture, and dual-export comparison.
• The initial inventory covers deterministic endpoint/route/tool/model/platform patterns; every unsupported surface kind is an explicit migration gap, never silently ignored.
• Live/device evidence policy starts conservative: absent or expired proof blocks verified.

13. Bug / Change Log

2026-07-13 — Establish Contract Graph rails

Type: Feature

Summary:

• Added the F105 scope, CUE architecture decision, test plan, and implementation sequence.

Reason:

• Manual registry/spec/test evidence can drift without a deterministic feature-proof graph.

Impact:

• Developer infrastructure only; no product behavior changes.

Tests:

• Verifier self-tests are written red before engine implementation.

Notes:

• F103 is the representative vertical pilot; F79 platform mismatch is recorded as a migration gap rather than altered without proof.

2026-08-05 — Exhaustive proof collection timeout

Type: CI reliability

Summary:

• The deploy-branch Contract Graph job reached its 45-minute timeout while the bounded native collector was still enumerating the repository’s proof inventory; no contract assertion had failed.
• The workflow, its hermetic policy test, and the deployment diagram now share a 75-minute budget, preserving the exhaustive collection contract instead of cancelling a truthful plan.

Reason:

• The current self-hosted runner’s cold Gradle, backend pytest, and frontend Vitest collection phases exceed the previous ceiling as the proof inventory grows.

Impact:

• Developer infrastructure only; no product behavior or proof semantics change.

2026-08-05 — Preserve Vitest proof IDs in collected test names

Type: CI reliability

Summary:

• The first post-timeout run completed collection but failed closed because two Vitest proofs were declared only as comments; Vitest’s JSON collector exposes test names, not comments.
• The affected F29 channel-preview and F77 notification-open tests now include their exact @lcg proof IDs in the test titles, preserving the existing contract without weakening the collector.

Reason:

• A proof that exists only in source text is not runner-native evidence; the graph must be able to locate the same ID in the collected test node.

Impact:

• Developer infrastructure only; no product behavior changes.