# Completion Contract

Audience: AI coding agents first.

## DONE = User-Usable

- NEVER call request complete when only source changed.
- MUST leave requested behavior in user-testable runtime state.
- Before reporting DONE:
  1. Run required tests, lint, and typecheck.
  2. Build production artifact used by actual launcher.
  3. Install/copy/reload/restart artifact or service when project workflow requires it and action is authorized.
  4. Probe launcher/runtime path to verify it resolves updated artifact.
  5. State exact test entrypoint user can run now.
- If active user-owned foreground process must restart, rebuild artifact first; report request BLOCKED, not DONE, until restart condition is explicit.
- Build output in alternate path does not count. Verify actual launcher precedence and artifact timestamp/hash.
- Tests against debug/test binary do not prove installed/release runtime changed.

DO NOT:

> Changed source. Tests pass. Done.

Required shape:

> Rebuilt artifact used by `<launcher>`. Runtime probe passed. Test now with `<entrypoint>`.

Example for TUI changes:

1. Run `cargo build --release --locked --manifest-path tui/Cargo.toml`.
2. Verify the installed `factory` entrypoint resolves the deployed Factory tree.
3. Restart existing TUI process because running process cannot load replaced executable.
4. Report user-testable key sequence only after steps 1–3 are satisfied or explicitly blocked on user-owned process.

## Landing to main

- `main` has ONE serialized writer (trunk-ownership). NEVER `git push` to main directly. NEVER `--force`.
- Land via `ship.sh land` (routes through `workflows/lib/finish-branch.sh`): fetch origin/main → gated candidate → fast-forward under lock.
- A `pre-push: rejected` on main is the guard working as designed — route through the lander, do NOT invent a bypass, reconcile by hand, or escalate.