obto-build-loop

OBTO App Build Loop

Before anything else

1. Call obto_whoami first in every new conversation. Read the user's domain, super-user status, operatorIdentity flag, and availableResources from the response.
2. The server is stateless (3.3.0+ contract): there is no session-level active app. Pass appName AND domain explicitly on every app-scoped tool call. Never assume a "current app" — if the user hasn't named one, ask, or discover with obto_list_all_apps / obto_find_app_by_name. (obto_set_active_app / obto_reset_domain / obto_create_app are RETIRED — do not call them.)
3. Operator identities (3.5.2): if whoami returns operatorIdentity: true, the home domain is the platform-operations domain — do NOT build user apps there. Ask the human which tenant domain to target. obto_scaffold_app refuses operator domains without an explicit confirmOperatorDomain: true (super-user only, logged).
4. Cross-tenant addressing (3.5.26): whoami's domain is only the connection vhost's default. Super-users (crossTenantEnabled: true) may pass ANY active tenant's domain per call — whoami also returns identityDomain (the identity's own tenant) and a tenantDomains registry summary (count + slugs) for discovery. Confirm a named tenant's slug against tenantDomains before writing; an unknown slug is refused with unknown_domain + didYouMean (typo guard). Regular users are pinned to their own domain (cross_tenant_not_allowed).
5. Read obto://guide/quickstart from the server's resources before the first deployment. The server-served guides are the source of truth — prefer them over assumptions. Scan the availableResources directory whoami returns and load the ones whose whenToRead fits the task — e.g. obto://guide/blueprints before writing code for a collection type, and obto://guide/public-app-baseline before claiming an app is done.

The build loop

Work in this order; do not skip steps:

1. Contract first. Write a one-paragraph build contract: (1) what the app does, (2) the FIRST vertical slice to ship, (3) what "done" means for that slice. Confirm with the user if scope is unclear — never invent scope. As of 3.5.2 this is the buildContract parameter obto_scaffold_app requires (missing → missing_build_contract refusal with a teaching hint); it is stored on the application record.
2. Scaffold. Use obto_scaffold_app for new apps (creates record + working skeleton in one call), passing buildContract and kind: 'public' for a browser web app (index page + App.tsx + App.css, ESM imports + relative ./ paths) or 'native' for an OBTO shell component (ui_template + policy_client + script_client, window-global libs + return ComponentName;). The skeleton passes obto_validate_app immediately and writes each artifact to its correct collection. The response includes structured nextSteps — follow them in order.
3. One vertical slice. Ship a single end-to-end path (one page, one route, one script) and verify it works before expanding. Anything beyond the contract's slice is a NEW slice the human approves — not a silent addition.
4. Verify after every write. After each obto_upsert_record / route change, read the artifact back (fetch by id <collection>::<app>::<domain>::<name>, or obto_grep_artifact for a slice of a large one) and confirm the content landed. Never claim a write succeeded without reading it back. For a code-bearing script, obto_validate_script also runs by reference — omit script and name the stored artifact — so you can validate exactly what the platform stored, not what you meant to send. (Known false-fire: a pltf_script_server module containing ESM syntax fails by-reference validation at line 1; that one signature is benign.)
5. Smoke gate before "done" — verify semantically, on the surface a real visitor uses. A preview URL proves only that the preview infra responded, and HTTP 200 proves nothing at all: OBTO's own "Site Missing" / "domain was not found" shells are served with status 200, so a status-only check certifies broken apps as working. "Done" means all of:
   • obto_validate_app returns no errors.
   • Every public API route called via obto_invoke_route returns the expected status, content type, and JSON shape. An HTML 200 on an /api/... route is a failure, never a response; so is a non-200, a 524/timeout, or a degraded-mode UI fallback.
   • The receipt says WHICH surface answered. connectVia:'canonical' means the real canonical host served it; a tenant_ingress_semantic_fallback (with canonicalAttempt + layerVerdict) means the canonical host served a platform shell and the tool fell back — that is a finding to report, not a pass. Fallback success is not canonical success.
   • For a published app, obto_get_build_status shows publish.status: 'published' with its per-surface verify evidence, and you have READ any caveats (a publish can be genuinely published and still carry a known platform degradation).
   • pltf_log (via obto_db_query) shows no runtime errors.
   • Where headless Chromium is provisioned, obto_capture_preview confirms the UI renders with clean console / pageErrors / failedRequests.
   • Best proof of all: exercise one real user action end to end and confirm it persisted (submit/vote/save, then read the record back through the app's own API).